Re: [PATCH 3/3] check-ref-format doc: --branch validates and expands

[Jeff King]

On Wed, Oct 18, 2017 at 05:55:18AM +0900, Junio C Hamano wrote:

> I'll take these three to replace what I tentatively queued, not
> necessarily because I like the change in 1/3 better, but because
> these are explained much better; besides I prefer a version that at
> least two people deeply looked at.

These look good to me. Between your two versions, I think the code in
Jonathan's is slightly preferable. It's possible that some other caller
of strbuf_check_branch_name() may run into the same thing and be fixed
(I am trying to think of a hypothetical caller that would be
inconvenienced by the new behavior, but I can't come up with one; and
certainly the existing code would BUG(), so this is an improvement).

-Peff

Re: [PATCH 3/3] check-ref-format doc: --branch validates and expands

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder  writes:

>> From: Junio C Hamano 
>>
>> "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 
>> Signed-off-by: Junio C Hamano 
>> ---
>
> Missing sign-off, unlike the other two, intended?

Oops.
Signed-off-by: Jonathan Nieder 

> I'll take these three to replace what I tentatively queued, not
> necessarily because I like the change in 1/3 better, but because
> these are explained much better; besides I prefer a version that at
> least two people deeply looked at.

Okay, thanks.  I'll add the rest of the change as a patch on top. :)

Thanks,
Jonathan

Re: [PATCH 3/3] check-ref-format doc: --branch validates and expands

[Junio C Hamano]

Jonathan Nieder  writes:

> From: Junio C Hamano 
>
> "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 
> Signed-off-by: Junio C Hamano 
> ---

Missing sign-off, unlike the other two, intended?

I'll take these three to replace what I tentatively queued, not
necessarily because I like the change in 1/3 better, but because
these are explained much better; besides I prefer a version that at
least two people deeply looked at.

Thanks.

[PATCH 3/3] check-ref-format doc: --branch validates and expands

[Jonathan Nieder]

From: Junio C Hamano 

"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 
Signed-off-by: Junio C Hamano 
---
 Documentation/git-check-ref-format.txt | 9 -
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-check-ref-format.txt 
b/Documentation/git-check-ref-format.txt
index 92777cef25..cf0a0b7df2 100644
--- a/Documentation/git-check-ref-format.txt
+++ b/Documentation/git-check-ref-format.txt
@@ -77,7 +77,14 @@ reference name expressions (see linkgit:gitrevisions[7]):
 
 . at-open-brace `@{` is used as a notation to access a reflog entry.
 
-With the `--branch` option, it expands the ``previous branch syntax''
+With the `--branch` 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).  The rule `git check-ref-format --branch $name` implements
+may be stricter than what `git check-ref-format refs/heads/$name`
+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 `--branch` option in a repository, the input is first
+expanded for 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
-- 
2.15.0.rc1.287.g2b38de12cc