2005-10-17 05:41:59 +00:00
|
|
|
git-check-ref-format(1)
|
|
|
|
|
=======================
|
|
|
|
|
|
|
|
|
|
NAME
|
|
|
|
|
----
|
2009-03-23 01:00:17 +00:00
|
|
|
git-check-ref-format - Ensures that a reference name is well formed
|
2005-10-17 05:41:59 +00:00
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
|
--------
|
2009-03-21 21:19:53 +00:00
|
|
|
[verse]
|
2011-09-15 21:10:30 +00:00
|
|
|
'git check-ref-format' [--normalize]
|
|
|
|
|
[--[no-]allow-onelevel] [--refspec-pattern]
|
|
|
|
|
<refname>
|
2009-10-12 05:28:23 +00:00
|
|
|
'git check-ref-format' --branch <branchname-shorthand>
|
2005-10-17 05:41:59 +00:00
|
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
|
-----------
|
2009-03-23 01:00:17 +00:00
|
|
|
Checks if a given 'refname' is acceptable, and exits with a non-zero
|
|
|
|
|
status if it is not.
|
2005-10-17 05:41:59 +00:00
|
|
|
|
|
|
|
|
A reference is used in git to specify branches and tags. A
|
2011-06-23 16:31:19 +00: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`).
|
|
|
|
|
|
docs: don't talk about $GIT_DIR/refs/ everywhere
It is misleading to say that we pull refs from $GIT_DIR/refs/*, because we
may also consult the packed refs mechanism. These days we tend to treat
the "refs hierarchy" as more of an abstract namespace that happens to be
represented as $GIT_DIR/refs. At best, this is a minor inaccuracy, but at
worst it can confuse users who then look in $GIT_DIR/refs and find that it
is missing some of the refs they expected to see.
This patch drops most uses of "$GIT_DIR/refs/*", changing them into just
"refs/*", under the assumption that users can handle the concept of an
abstract refs namespace. There are a few things to note:
- most cases just dropped the $GIT_DIR/ portion. But for cases where
that left _just_ the word "refs", I changed it to "refs/" to help
indicate that it was a hierarchy. I didn't do the same for longer
paths (e.g., "refs/heads" remained, instead of becoming
"refs/heads/").
- in some cases, no change was made, as the text was explicitly about
unpacked refs (e.g., the discussion in git-pack-refs).
- In some cases it made sense instead to note the existence of packed
refs (e.g., in check-ref-format and rev-parse).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2010-02-18 01:16:20 +00:00
|
|
|
git imposes the following rules on how references are named:
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2009-03-23 01:00:17 +00:00
|
|
|
. They can include slash `/` for hierarchical (directory)
|
2006-06-07 12:56:45 +00:00
|
|
|
grouping, but no slash-separated component can begin with a
|
2011-09-15 21:10:27 +00:00
|
|
|
dot `.` or end with the sequence `.lock`.
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2009-05-13 15:43:06 +00: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 21:10:23 +00:00
|
|
|
restricted. If the `--allow-onelevel` option is used, this rule
|
|
|
|
|
is waived.
|
2009-05-13 15:43:06 +00:00
|
|
|
|
2009-03-23 01:00:17 +00:00
|
|
|
. They cannot have two consecutive dots `..` anywhere.
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2009-03-23 01:00:17 +00:00
|
|
|
. They cannot have ASCII control characters (i.e. bytes whose
|
2005-10-17 05:41:59 +00:00
|
|
|
values are lower than \040, or \177 `DEL`), space, tilde `~`,
|
2011-09-15 21:10:23 +00:00
|
|
|
caret `{caret}`, or colon `:` anywhere.
|
|
|
|
|
|
|
|
|
|
. They cannot have question-mark `?`, asterisk `{asterisk}`, or open
|
|
|
|
|
bracket `[` anywhere. See the `--refspec-pattern` option below for
|
|
|
|
|
an exception to this rule.
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2011-09-15 21:10:30 +00: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 20:27:31 +00:00
|
|
|
|
|
|
|
|
. They cannot contain a sequence `@{`.
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2010-02-12 23:39:03 +00:00
|
|
|
. They cannot contain a `\`.
|
2009-05-08 05:32:37 +00:00
|
|
|
|
2009-03-23 01:00:17 +00: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
|
2005-12-16 02:03:59 +00:00
|
|
|
unquoted (by mistake), and also avoids ambiguities in certain
|
2010-10-11 16:03:32 +00:00
|
|
|
reference name expressions (see linkgit:gitrevisions[7]):
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2009-03-23 01:00:17 +00:00
|
|
|
. A double-dot `..` is often used as in `ref1..ref2`, and in some
|
|
|
|
|
contexts this notation means `{caret}ref1 ref2` (i.e. not in
|
|
|
|
|
`ref1` and in `ref2`).
|
2005-10-17 05:41:59 +00:00
|
|
|
|
2009-03-23 01:00:17 +00:00
|
|
|
. A tilde `~` and caret `{caret}` are used to introduce the postfix
|
2005-10-17 05:41:59 +00:00
|
|
|
'nth parent' and 'peel onion' operation.
|
|
|
|
|
|
2009-03-23 01:00:17 +00:00
|
|
|
. A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s
|
2005-10-17 05:41:59 +00:00
|
|
|
value and store it in dstref" in fetch and push operations.
|
2006-05-21 02:03:14 +00:00
|
|
|
It may also be used to select a specific object such as with
|
2010-01-09 23:33:00 +00:00
|
|
|
'git cat-file': "git cat-file blob v1.3.3:refs.c".
|
2005-10-17 05:41:59 +00: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 20:27:31 +00:00
|
|
|
. at-open-brace `@{` is used as a notation to access a reflog entry.
|
|
|
|
|
|
2009-10-12 05:28:23 +00: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 21:19:53 +00:00
|
|
|
|
2011-09-15 21:10:23 +00:00
|
|
|
OPTIONS
|
|
|
|
|
-------
|
|
|
|
|
--allow-onelevel::
|
|
|
|
|
--no-allow-onelevel::
|
|
|
|
|
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
|
|
|
|
|
enabled, <refname> is allowed to contain a single `{asterisk}`
|
|
|
|
|
in place of a one full pathname component (e.g.,
|
|
|
|
|
`foo/{asterisk}/bar` but not `foo/bar{asterisk}`).
|
|
|
|
|
|
2011-09-15 21:10:30 +00: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-12 23:39:43 +00:00
|
|
|
EXAMPLES
|
|
|
|
|
--------
|
2009-03-21 21:19:53 +00:00
|
|
|
|
2009-10-12 23:39:43 +00:00
|
|
|
* Print the name of the previous branch:
|
|
|
|
|
+
|
|
|
|
|
------------
|
|
|
|
|
$ git check-ref-format --branch @{-1}
|
|
|
|
|
------------
|
|
|
|
|
|
|
|
|
|
* Determine the reference name to use for a new branch:
|
|
|
|
|
+
|
|
|
|
|
------------
|
2011-09-15 21:10:30 +00:00
|
|
|
$ ref=$(git check-ref-format --normalize "refs/heads/$newbranch") ||
|
2009-10-12 23:39:43 +00:00
|
|
|
die "we do not like '$newbranch' as a branch name."
|
|
|
|
|
------------
|
2005-10-17 05:41:59 +00:00
|
|
|
|
|
|
|
|
GIT
|
|
|
|
|
---
|
2008-06-06 07:07:32 +00:00
|
|
|
Part of the linkgit:git[1] suite
|