Re: Git commands version documentation

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: May 23, 2022, 18:01 UTC
Message-ID: <220523.86o7zoxgzo.gmgdl@evledraar.gmail.com>
In-Reply-To: <96cd59ea-ea75-e33e-758f-abe16f9cca0f@iee.email>

On Mon, May 23 2022, Philip Oakley wrote:

Show 41 quoted lines

> Hi Ævar
>
> On 23/05/2022 14:08, Ævar Arnfjörð Bjarmason wrote:
>> On Mon, May 23 2022, Philip Oakley wrote:
>>
>>> Hi Junio,
>>>
>>> On 23/05/2022 00:35, Junio C Hamano wrote:
>>>> Philip Oakley <philipoakley@iee.email> writes:
>>>>
>>>>> One manual method is to look at the history (blame) for the respective
>>>>> man pages to see when the man page was initially committed, and when
>>>>> appropriate options were added.
>>>>>
>>>>> Maybe use one of the hosting providers GUI if that is your choice e.g.
>>>>> https://github.com/git/git/blame/master/Documentation/git-gc.txt
>>>> I got an impression that blame/log is an overkill for the request,
>>>> which asks for "what tagged version?", to which the answer would be
>>>> to compare the manual pages for each release (or scan the release
>>>> notes), perhaps?
>>>>
>>>>
>>> I was also concerned as to which way the problem was being addressed:
>>> was it a need for a cross reference table for all commands, or was it 
>>> for just a select few?
>>>
>>> For me, who likes a good UI, I found the GitHub blame UI quite useful
>>> when looking at files from the latter direction. It was much easier to 
>>> scan the blame for the command's documentation page than try and scan
>>> through the endless release notes. Obviously this does expect that our 
>>> documentation is fairly complete, at least at the 'mention an option'
>>> level, even if the occasional nuance didn't reach the docs.
>>>
>>>
>>> I can see that a cli terminal representation is likely to be harder to
>>> scan, and that some hosters don't provide a blame page, so it would be
>>> a 'horses for courses' choice.
>> I think asking a git user to use "git blame" on our own source code is a
>> non-starter in terms of where we'd like to eventually get. 
>
> "we?"

We as a project.

Show 9 quoted lines

>> E.g. we could carry a text file in our sources with a list of what
>> commands existed at what versions, and what options they had (as
>> extracted from the parse-options reflection mechanism). Rather than
>> manually maintain such a list we could carry a script to that would
>> attempt to build past releases, for any that were missing we'd attempt
>> to build them and fill in the gaps.
>
> Implicit in this is the choice between parsing the code, or the
> documentation, to determine when options started appearing.

By "extracted from the parse-options reflection" I mean that you could script this around the same facility we use to dump what options we support for the bash completion.

See parse-options.c, all users of the API support a hidden option to dump their supported options, and likewise git.c can dump built-ins and other known lists of commands.

So in theory this sort of thing should be a relativel simple for-loop that builds our release tags, for each successful builds lists the built-ins, and for each of those lists the options.

The options being a bonus, it would already be useful if it just did command.

> In some ways it sounds very similar to the i18n efforts where the
> 'database' grows with every release. Though capturing the historic
> release progression is probably the hardest part.

As long as we can still build that release it should be pretty easy...