check-ref-format doc: --branch validates and expands <branch>
"git check-ref-format --branch $name" feature was originally introduced (and was advertised) as a way for scripts to take any end-user supplied string (like "master", "@{-1}" etc.) and see if it is usable when Git expects to see a branch name, and also obtain the concrete branch name that the at-mark magic expands to. Emphasize that "see if it is usable" role in the description and clarify that the @{...} expansion only occurs when run from within a repository. [jn: split out from a larger patch] Helped-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Oct 17, 2017 at 00:12 UTC
89dd32aedcb52a77240f3923a687edc8a61662e7
1 file changed
+8
-1
Documentation/git-check-ref-format.txt
+8
-1
@@ -77,7 +77,14 @@ reference name expressions (see linkgit:gitrevisions[7]):
77
78
. at-open-brace `@{` is used as a notation to access a reflog entry.
79
80
-With the `--branch` option, it expands the ``previous branch syntax''
80
+With the `--branch` option, the command takes a name and checks if
81
+it can be used as a valid branch name (e.g. when creating a new
82
+branch). The rule `git check-ref-format --branch $name` implements
83
+may be stricter than what `git check-ref-format refs/heads/$name`
84
+says (e.g. a dash may appear at the beginning of a ref component,
85
+but it is explicitly forbidden at the beginning of a branch name).
86
+When run with `--branch` option in a repository, the input is first
87
+expanded for the ``previous branch syntax''
88
`@{-n}`. For example, `@{-1}` is a way to refer the last branch you
89
were on. This option should be used by porcelains to accept this
90
syntax anywhere a branch name is expected, so they can act as if you