2005-10-17 07:41:59 +02:00
|
|
|
git-check-ref-format(1)
|
|
|
|
|
=======================
|
|
|
|
|
|
|
|
|
|
NAME
|
|
|
|
|
----
|
2009-03-23 02:00:17 +01:00
|
|
|
git-check-ref-format - Ensures that a reference name is well formed
|
2005-10-17 07:41:59 +02:00
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
|
--------
|
2009-03-21 22:19:53 +01:00
|
|
|
[verse]
|
2011-09-15 23:10:30 +02:00
|
|
|
'git check-ref-format' [--normalize]
|
|
|
|
|
[--[no-]allow-onelevel] [--refspec-pattern]
|
|
|
|
|
<refname>
|
2009-10-12 07:28:23 +02:00
|
|
|
'git check-ref-format' --branch <branchname-shorthand>
|
2005-10-17 07:41:59 +02:00
|
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
|
-----------
|
2009-03-23 02:00:17 +01:00
|
|
|
Checks if a given 'refname' is acceptable, and exits with a non-zero
|
|
|
|
|
status if it is not.
|
2005-10-17 07:41:59 +02:00
|
|
|
|
2013-01-21 20:17:53 +01:00
|
|
|
A reference is used in Git to specify branches and tags. A
|
2011-06-23 18:31:19 +02:00
|
|
|
branch head is stored in the `refs/heads` hierarchy, while
|
|
|
|
|
a tag is stored in the `refs/tags` hierarchy of the ref namespace
|
|
|
|
|
(typically in `$GIT_DIR/refs/heads` and `$GIT_DIR/refs/tags`
|
|
|
|
|
directories or, as entries in file `$GIT_DIR/packed-refs`
|
|
|
|
|
if refs are packed by `git gc`).
|
|
|
|
|
|
2013-01-21 20:17:53 +01:00
|
|
|
Git imposes the following rules on how references are named:
|
2005-10-17 07:41:59 +02:00
|
|
|
|
2009-03-23 02:00:17 +01:00
|
|
|
. They can include slash `/` for hierarchical (directory)
|
2006-06-07 14:56:45 +02:00
|
|
|
grouping, but no slash-separated component can begin with a
|
2011-09-15 23:10:27 +02:00
|
|
|
dot `.` or end with the sequence `.lock`.
|
2005-10-17 07:41:59 +02:00
|
|
|
|
2009-05-13 17:43:06 +02:00
|
|
|
. They must contain at least one `/`. This enforces the presence of a
|
|
|
|
|
category like `heads/`, `tags/` etc. but the actual names are not
|
2011-09-15 23:10:23 +02:00
|
|
|
restricted. If the `--allow-onelevel` option is used, this rule
|
|
|
|
|
is waived.
|
2009-05-13 17:43:06 +02:00
|
|
|
|
2009-03-23 02:00:17 +01:00
|
|
|
. They cannot have two consecutive dots `..` anywhere.
|
2005-10-17 07:41:59 +02:00
|
|
|
|
2009-03-23 02:00:17 +01:00
|
|
|
. They cannot have ASCII control characters (i.e. bytes whose
|
2005-10-17 07:41:59 +02:00
|
|
|
values are lower than \040, or \177 `DEL`), space, tilde `~`,
|
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
|
|
|
caret `^`, or colon `:` anywhere.
|
2011-09-15 23:10:23 +02:00
|
|
|
|
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
|
|
|
. They cannot have question-mark `?`, asterisk `*`, or open
|
2011-09-15 23:10:23 +02:00
|
|
|
bracket `[` anywhere. See the `--refspec-pattern` option below for
|
|
|
|
|
an exception to this rule.
|
2005-10-17 07:41:59 +02:00
|
|
|
|
2011-09-15 23:10:30 +02:00
|
|
|
. They cannot begin or end with a slash `/` or contain multiple
|
|
|
|
|
consecutive slashes (see the `--normalize` option below for an
|
|
|
|
|
exception to this rule)
|
|
|
|
|
|
|
|
|
|
. They cannot end with a dot `.`.
|
check_ref_format(): tighten refname rules
This changes the rules for refnames to forbid:
(1) a refname that contains "@{" in it.
Some people and foreign SCM converter may have named their branches
as frotz@24 and we still want to keep supporting it.
However, "git branch frotz@{24}" is a disaster. It cannot even
checked out because "git checkout frotz@{24}" will interpret it as
"detach the HEAD at twenty-fourth reflog entry of the frotz branch".
(2) a refname that ends with a dot.
We already reject a path component that begins with a dot, primarily
to avoid ambiguous range interpretation. If we allowed ".B" as a
valid ref, it is unclear if "A...B" means "in dot-B but not in A" or
"either in A or B but not in both".
But for this to be complete, we need also to forbid "A." to avoid "in
B but not in A-dot". This was not a problem in the original range
notation, but we should have added this restriction when three-dot
notation was introduced.
Unlike "no dot at the beginning of any path component" rule, this
rule does not have to be "no dot at the end of any path component",
because you cannot abbreviate the tail end away, similar to you can
say "dot-B" to mean "refs/heads/dot-B".
For these reasons, it is not likely people created branches with these
names on purpose, but we have allowed such names to be used for quite some
time, and it is possible that people created such branches by mistake or
by accident.
To help people with branches with such unfortunate names to recover,
we still allow "branch -d 'bad.'" to delete such branches, and also allow
"branch -m bad. good" to rename them.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-21 21:27:31 +01:00
|
|
|
|
|
|
|
|
. They cannot contain a sequence `@{`.
|
2005-10-17 07:41:59 +02:00
|
|
|
|
Add new @ shortcut for HEAD
Typing 'HEAD' is tedious, especially when we can use '@' instead.
The reason for choosing '@' is that it follows naturally from the
ref@op syntax (e.g. HEAD@{u}), except we have no ref, and no
operation, and when we don't have those, it makes sens to assume
'HEAD'.
So now we can use 'git show @~1', and all that goody goodness.
Until now '@' was a valid name, but it conflicts with this idea, so
let's make it invalid. Probably very few people, if any, used this name.
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2013-09-02 08:34:30 +02:00
|
|
|
. They cannot be the single character `@`.
|
|
|
|
|
|
2010-02-13 00:39:03 +01:00
|
|
|
. They cannot contain a `\`.
|
2009-05-08 07:32:37 +02:00
|
|
|
|
2009-03-23 02:00:17 +01:00
|
|
|
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
|
2015-12-04 19:09:32 +01:00
|
|
|
unquoted (by mistake), and also avoid ambiguities in certain
|
2010-10-11 18:03:32 +02:00
|
|
|
reference name expressions (see linkgit:gitrevisions[7]):
|
2005-10-17 07:41:59 +02:00
|
|
|
|
2009-03-23 02:00:17 +01:00
|
|
|
. A double-dot `..` is often used as in `ref1..ref2`, and in some
|
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
|
|
|
contexts this notation means `^ref1 ref2` (i.e. not in
|
2009-03-23 02:00:17 +01:00
|
|
|
`ref1` and in `ref2`).
|
2005-10-17 07:41:59 +02:00
|
|
|
|
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
|
|
|
. A tilde `~` and caret `^` are used to introduce the postfix
|
2005-10-17 07:41:59 +02:00
|
|
|
'nth parent' and 'peel onion' operation.
|
|
|
|
|
|
2009-03-23 02:00:17 +01:00
|
|
|
. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
|
2005-10-17 07:41:59 +02:00
|
|
|
value and store it in dstref" in fetch and push operations.
|
2006-05-21 04:03:14 +02:00
|
|
|
It may also be used to select a specific object such as with
|
2010-01-10 00:33:00 +01:00
|
|
|
'git cat-file': "git cat-file blob v1.3.3:refs.c".
|
2005-10-17 07:41:59 +02:00
|
|
|
|
check_ref_format(): tighten refname rules
This changes the rules for refnames to forbid:
(1) a refname that contains "@{" in it.
Some people and foreign SCM converter may have named their branches
as frotz@24 and we still want to keep supporting it.
However, "git branch frotz@{24}" is a disaster. It cannot even
checked out because "git checkout frotz@{24}" will interpret it as
"detach the HEAD at twenty-fourth reflog entry of the frotz branch".
(2) a refname that ends with a dot.
We already reject a path component that begins with a dot, primarily
to avoid ambiguous range interpretation. If we allowed ".B" as a
valid ref, it is unclear if "A...B" means "in dot-B but not in A" or
"either in A or B but not in both".
But for this to be complete, we need also to forbid "A." to avoid "in
B but not in A-dot". This was not a problem in the original range
notation, but we should have added this restriction when three-dot
notation was introduced.
Unlike "no dot at the beginning of any path component" rule, this
rule does not have to be "no dot at the end of any path component",
because you cannot abbreviate the tail end away, similar to you can
say "dot-B" to mean "refs/heads/dot-B".
For these reasons, it is not likely people created branches with these
names on purpose, but we have allowed such names to be used for quite some
time, and it is possible that people created such branches by mistake or
by accident.
To help people with branches with such unfortunate names to recover,
we still allow "branch -d 'bad.'" to delete such branches, and also allow
"branch -m bad. good" to rename them.
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2009-03-21 21:27:31 +01:00
|
|
|
. at-open-brace `@{` is used as a notation to access a reflog entry.
|
|
|
|
|
|
2009-10-12 07:28:23 +02:00
|
|
|
With the `--branch` option, it expands the ``previous branch syntax''
|
|
|
|
|
`@{-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.
|
2009-03-21 22:19:53 +01:00
|
|
|
|
2011-09-15 23:10:23 +02:00
|
|
|
OPTIONS
|
|
|
|
|
-------
|
2013-05-09 03:16:55 +02:00
|
|
|
--[no-]allow-onelevel::
|
2011-09-15 23:10:23 +02:00
|
|
|
Controls whether one-level refnames are accepted (i.e.,
|
|
|
|
|
refnames that do not contain multiple `/`-separated
|
|
|
|
|
components). The default is `--no-allow-onelevel`.
|
|
|
|
|
|
|
|
|
|
--refspec-pattern::
|
|
|
|
|
Interpret <refname> as a reference name pattern for a refspec
|
|
|
|
|
(as used with remote repositories). If this option is
|
docs: stop using asciidoc no-inline-literal
In asciidoc 7, backticks like `foo` produced a typographic
effect, but did not otherwise affect the syntax. In asciidoc
8, backticks introduce an "inline literal" inside which markup
is not interpreted. To keep compatibility with existing
documents, asciidoc 8 has a "no-inline-literal" attribute to
keep the old behavior. We enabled this so that the
documentation could be built on either version.
It has been several years now, and asciidoc 7 is no longer
in wide use. We can now decide whether or not we want
inline literals on their own merits, which are:
1. The source is much easier to read when the literal
contains punctuation. You can use `master~1` instead
of `master{tilde}1`.
2. They are less error-prone. Because of point (1), we
tend to make mistakes and forget the extra layer of
quoting.
This patch removes the no-inline-literal attribute from the
Makefile and converts every use of backticks in the
documentation to an inline literal (they must be cleaned up,
or the example above would literally show "{tilde}" in the
output).
Problematic sites were found by grepping for '`.*[{\\]' and
examined and fixed manually. The results were then verified
by comparing the output of "html2text" on the set of
generated html pages. Doing so revealed that in addition to
making the source more readable, this patch fixes several
formatting bugs:
- HTML rendering used the ellipsis character instead of
literal "..." in code examples (like "git log A...B")
- some code examples used the right-arrow character
instead of '->' because they failed to quote
- api-config.txt did not quote tilde, and the resulting
HTML contained a bogus snippet like:
<tt><sub></tt> foo <tt></sub>bar</tt>
which caused some parsers to choke and omit whole
sections of the page.
- git-commit.txt confused ``foo`` (backticks inside a
literal) with ``foo'' (matched double-quotes)
- mentions of `A U Thor <author@example.com>` used to
erroneously auto-generate a mailto footnote for
author@example.com
- the description of --word-diff=plain incorrectly showed
the output as "[-removed-] and {added}", not "{+added+}".
- using "prime" notation like:
commit `C` and its replacement `C'`
confused asciidoc into thinking that everything between
the first backtick and the final apostrophe were meant
to be inside matched quotes
- asciidoc got confused by the escaping of some of our
asterisks. In particular,
`credential.\*` and `credential.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2012-04-26 10:51:57 +02:00
|
|
|
enabled, <refname> is allowed to contain a single `*`
|
2015-07-22 23:05:33 +02:00
|
|
|
in the refspec (e.g., `foo/bar*/baz` or `foo/bar*baz/`
|
|
|
|
|
but not `foo/bar*/baz*`).
|
2011-09-15 23:10:23 +02:00
|
|
|
|
2011-09-15 23:10:30 +02:00
|
|
|
--normalize::
|
|
|
|
|
Normalize 'refname' by removing any leading slash (`/`)
|
|
|
|
|
characters and collapsing runs of adjacent slashes between
|
|
|
|
|
name components into a single slash. Iff the normalized
|
|
|
|
|
refname is valid then print it to standard output and exit
|
|
|
|
|
with a status of 0. (`--print` is a deprecated way to spell
|
|
|
|
|
`--normalize`.)
|
|
|
|
|
|
|
|
|
|
|
2009-10-13 01:39:43 +02:00
|
|
|
EXAMPLES
|
|
|
|
|
--------
|
2009-03-21 22:19:53 +01:00
|
|
|
|
2009-10-13 01:39:43 +02:00
|
|
|
* Print the name of the previous branch:
|
|
|
|
|
+
|
|
|
|
|
------------
|
|
|
|
|
$ git check-ref-format --branch @{-1}
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
* Determine the reference name to use for a new branch:
|
|
|
|
|
+
|
|
|
|
|
------------
|
2016-09-20 09:33:14 +02:00
|
|
|
$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch")||
|
|
|
|
|
{ echo "we do not like '$newbranch' as a branch name." >&2 ; exit 1 ; }
|
2009-10-13 01:39:43 +02:00
|
|
|
------------
|
2005-10-17 07:41:59 +02:00
|
|
|
|
|
|
|
|
GIT
|
|
|
|
|
---
|
2008-06-06 09:07:32 +02:00
|
|
|
Part of the linkgit:git[1] suite
|