On Mon, May 23 2022, Philip Oakley wrote: > 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. >> 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...
