Surprising 'git-describe --all --match' behavior.

Surprising 'git-describe --all --match' behavior.

[Sergei Organov]

Hello,

Just playing with it, got some surprises:

$ git --version
git version 1.9.3

$ git describe --all
heads/v3.5
$ git describe --all --match 'v*'
tags/v3.5.6b2-4-gab4bf78
$ git describe --all --match 'heads/v*'
fatal: No names found, cannot describe anything.


... "heads/v3.5" matches neither 'v*' nor 'heads/v*'?

$ git describe --all --match 'v*'
tags/v3.5.6b2-4-gab4bf78
$ git describe --all --match 'tags/v*'
fatal: No names found, cannot describe anything.

... git matches short names when outputs full names?

Is it a defect, or what do I miss?

-- 
Sergei.

Re: Surprising 'git-describe --all --match' behavior.

[Junio C Hamano]

Sergei Organov <osv@javad.com> writes:

> Just playing with it, got some surprises:
>
> $ git --version
> git version 1.9.3
>
> $ git describe --all
> heads/v3.5
> $ git describe --all --match 'v*'
> tags/v3.5.6b2-4-gab4bf78
> $ git describe --all --match 'heads/v*'
> fatal: No names found, cannot describe anything.

I think

$ git describe --help

       ...
       --match <pattern>
           Only consider tags matching the given glob(7) pattern,
           excluding the "refs/tags/" prefix. This can be used to
           avoid leaking private tags from the repository.
       ...

is poorly phrased, especially its "excluding" part.  What it wants
to say is "You give <pattern> but without refs/tags/, because the
program helpfully always prepend refs/tags/ to your pattern and
limit the output to those that match".  Hence you gave 'v*' as
<pattern> and limited the output to those that match 'refs/tags/v*'
(or you gave 'heads/v*' and limited to 'refs/tags/heads/v*').

Re: Surprising 'git-describe --all --match' behavior.

[Sergei Organov]

Junio C Hamano <gitster@pobox.com> writes:

> Sergei Organov <osv@javad.com> writes:
>
>> Just playing with it, got some surprises:
>>
>> $ git --version
>> git version 1.9.3
>>
>> $ git describe --all
>> heads/v3.5
>> $ git describe --all --match 'v*'
>> tags/v3.5.6b2-4-gab4bf78
>> $ git describe --all --match 'heads/v*'
>> fatal: No names found, cannot describe anything.
>
> I think
>
> $ git describe --help
>
>        ...
>        --match <pattern>
>            Only consider tags matching the given glob(7) pattern,
>            excluding the "refs/tags/" prefix. This can be used to
>            avoid leaking private tags from the repository.
>        ...
>
> is poorly phrased, especially its "excluding" part.  What it wants
> to say is "You give <pattern> but without refs/tags/, because the
> program helpfully always prepend refs/tags/ to your pattern and
> limit the output to those that match".  Hence you gave 'v*' as
> <pattern> and limited the output to those that match 'refs/tags/v*'
> (or you gave 'heads/v*' and limited to 'refs/tags/heads/v*').

OK, thanks, at least I now see how it works. So no <pattern> can ever
match any reference but tag, even when --all switch is given? If so,
appearance of --match effectively turns --all into --tags, that is still
rather confusing, isn't it?

Will something break if it won't helpfully prepend refs/tags/ once
--all is given?

-- 
Sergei.

Re: Surprising 'git-describe --all --match' behavior.

[Junio C Hamano]

Sergei Organov <osv@javad.com> writes:

> Will something break if it won't helpfully prepend refs/tags/ once
> --all is given?

"describe --all --match 'v*'" will no longer match a tag v1.2.3, and
forces the users to say "describe --match 'refs/tags/v*'", and these
users will probably see it as a new breakage, I would imagine.

Re: Surprising 'git-describe --all --match' behavior.

[Sergei Organov]

Junio C Hamano <gitster@pobox.com> writes:

> Sergei Organov <osv@javad.com> writes:
>
>> Will something break if it won't helpfully prepend refs/tags/ once
>> --all is given?
>
> "describe --all --match 'v*'" will no longer match a tag v1.2.3, and
> forces the users to say "describe --match 'refs/tags/v*'",

No,

descirbe --match 'v*'

or

describe --tags --match 'v*'

depending on what they actually meant. Notice my "once --all is given"
above. 

Those who used --all meant to match against all the refs, no?

> and these users will probably see it as a new breakage, I would imagine.

But why would anybody use --all --match if they only meant --tags
--match or even just --match alone? Was it historically --all that was
first introduced, maybe? 

-- 
Sergei.

Re: Surprising 'git-describe --all --match' behavior.

[Junio C Hamano]

Sergei Organov <osv@javad.com> writes:

> Junio C Hamano <gitster@pobox.com> writes:
>
>> Sergei Organov <osv@javad.com> writes:
>>
>>> Will something break if it won't helpfully prepend refs/tags/ once
>>> --all is given?
>>
>> "describe --all --match 'v*'" will no longer match a tag v1.2.3, and
>> forces the users to say "describe --match 'refs/tags/v*'",
>
> No,
>
> descirbe --match 'v*'
>
> or
>
> describe --tags --match 'v*'
>
> depending on what they actually meant. Notice my "once --all is given"
> above.  ...
> Those who used --all meant to match against all the refs, no?

I noticed it when I responded and ignored it as unworkable, because
it would make the interface inconsistent by making the meaning of
one option (i.e. --match) change depending on an unrelated option
(i.e. --all or --tags).

You can argue both ways: Those who read the doc and used --match
did mean to limit to tags.

The thing is, you cannot change it without risking to break existing
usage.  That does not necessarily mean you can never change
anything.  You only need to craft a careful transition plan to
minimize the pain for those who will be broken, and the end result
will be good if the pain is small enough and the benefit is large
enough ;)