Re: [PATCH 1/3] docs: adjust for the recent rename of `pu` to `seen`

[Junio C Hamano <gitster@pobox.com>]

Đoàn Trần Công Danh  <congdanhqx@gmail.com> writes:

> Hi Dscho,
>
> On 2020-06-23 15:04:13+0000, Johannes Schindelin via GitGitGadget <gitgitgadget@gmail.com> wrote:
>> diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt
>> index 0a5c8b7d493..492e573856f 100644
>> --- a/Documentation/git-ls-remote.txt
>> +++ b/Documentation/git-ls-remote.txt
>> @@ -101,9 +101,9 @@ f25a265a342aed6041ab0cc484224d9ca54b6f41	refs/tags/v0.99.1
>>  7ceca275d047c90c0c7d5afb13ab97efdf51bd6e	refs/tags/v0.99.3
>>  c5db5456ae3b0873fc659c19fafdde22313cc441	refs/tags/v0.99.2
>>  0918385dbd9656cab0d1d81ba7453d49bbc16250	refs/tags/junio-gpg-pub
>> -$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc
>> +$ git ls-remote http://www.kernel.org/pub/scm/git/git.git master seen rc
>
> rc is not with us anymore.
>
> Should we replace it with next, too?

I do not think so.  I think we never had 'rc'.

I think what the above example is demonstrating is this.

    SYNOPSIS calls the last command line arguments <refs>; they are
    actually mere patterns (which is how these command line
    arguments are described in the documentation).  It is *not* an
    error if no refs match a particular pattern.

And because we have no refs that match the pattern "rc", we only see
"master" and "pu" (now "seen") from the command.

I see a couple of possible improvements here:

 - The "<refs>...::" documentation should explain what kind of
   pattern match is performed here.  I recall these originally were
   just tail matches, but the rule might have been made more
   flexible over time.

 - The example should first explain the setting.  The first sample
   depends on the current (./.) repository having these tags or it
   would not work (showing the sample upfront and explaining the
   outcome shown in the sample would work well in this case,
   e.g. "we can see that in the current repository, there are tags
   X, Y and Z").  The second one at least needs to say two things:
   the sample repository does not have a branch called 'rc' and that
   is why it is not shown, and it is not an error for patterns to
   produce no match.

Thanks.

>
>>  5fe978a5381f1fbad26a80e682ddd2a401966740	refs/heads/master
>> -c781a84b5204fb294c9ccc79f8b3baceeb32c061	refs/heads/pu
>> +c781a84b5204fb294c9ccc79f8b3baceeb32c061	refs/heads/seen
>>  $ git remote add korg http://www.kernel.org/pub/scm/git/git.git
>>  $ git ls-remote --tags korg v\*
>>  d6602ec5194c87b0fc87103ca4d67251c76f233a	refs/tags/v0.99