{"thread":{"id":"57911","subject":"Git commands version documentation","startedAt":"2022-05-22T18:41:49Z","lastAt":"2022-05-23T18:30:51Z","messageCount":7,"participants":["Hrushikesh Rao","Philip Oakley","Junio C Hamano","Ævar Arnfjörð Bjarmason"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"455730","messageId":"ccb312dc-c2cc-ca3a-e659-0f87ceec0d15@gmail.com","threadId":"57911","inReplyTo":null,"subject":"Git commands version documentation","fromName":"Hrushikesh Rao","fromEmail":"hrushikesh20thegreat@gmail.com","sentAt":"2022-05-22T18:41:40Z","receivedAt":"2022-05-22T18:41:49Z","isPatch":false,"sender":{"key":"hrushikesh20thegreat@gmail.com","avatar":null},"body":"Hey,\n\nI am working on git maintenance project in Jenkins. We are using \ngit-maintenance to improve the performance of the git commands further \nimproving the build speed. Git maintenance was added in git version \n2.30.0. The aim of the project is to also support systems having git \nversion < 2.30.0. Few git maintenance tasks very available before the \nmaintenance command was introduced i.e gc,commit-graph,gc and \nincremental repack. Is there a way for me to find out in which version \nthese commands have been introduced? Based on this we can support legacy \ngit version.\n\nWaiting for your response.\n\nThank You\n\nHrushikesh Rao Naidnur\n\n"},{"id":"455733","messageId":"f3814646-4763-62e1-b64e-d1aab3fdbbc8@iee.email","threadId":"57911","inReplyTo":"ccb312dc-c2cc-ca3a-e659-0f87ceec0d15@gmail.com","subject":"Re: Git commands version documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-05-22T22:02:43Z","receivedAt":"2022-05-22T22:02:49Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 22/05/2022 19:41, Hrushikesh Rao wrote:\n> Hey,\n>\n> I am working on git maintenance project in Jenkins. We are using\n> git-maintenance to improve the performance of the git commands further\n> improving the build speed. Git maintenance was added in git version\n> 2.30.0. The aim of the project is to also support systems having git\n> version < 2.30.0. Few git maintenance tasks very available before the\n> maintenance command was introduced i.e gc,commit-graph,gc and\n> incremental repack. \n\n> Is there a way for me to find out in which version these commands have\n> been introduced? Based on this we can support legacy git version.\n\nOne manual method is to look at the history (blame) for the respective\nman pages to see when the man page was initially committed, and when\nappropriate options were added.\n\nMaybe use one of the hosting providers GUI if that is your choice e.g.\nhttps://github.com/git/git/blame/master/Documentation/git-gc.txt\n\n--\nPhilip\n"},{"id":"455735","messageId":"xmqqr14l87jp.fsf@gitster.g","threadId":"57911","inReplyTo":"f3814646-4763-62e1-b64e-d1aab3fdbbc8@iee.email","subject":"Re: Git commands version documentation","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-05-22T23:35:38Z","receivedAt":"2022-05-22T23:36:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley <philipoakley@iee.email> writes:\n\n> One manual method is to look at the history (blame) for the respective\n> man pages to see when the man page was initially committed, and when\n> appropriate options were added.\n>\n> Maybe use one of the hosting providers GUI if that is your choice e.g.\n> https://github.com/git/git/blame/master/Documentation/git-gc.txt\n\nI got an impression that blame/log is an overkill for the request,\nwhich asks for \"what tagged version?\", to which the answer would be\nto compare the manual pages for each release (or scan the release\nnotes), perhaps?\n\n\n"},{"id":"455763","messageId":"3067d8e3-15a7-75fc-20d7-90de0fc3fee6@iee.email","threadId":"57911","inReplyTo":"xmqqr14l87jp.fsf@gitster.g","subject":"Re: Git commands version documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-05-23T11:10:00Z","receivedAt":"2022-05-23T11:10:11Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Junio,\n\nOn 23/05/2022 00:35, Junio C Hamano wrote:\n> Philip Oakley <philipoakley@iee.email> writes:\n>\n>> One manual method is to look at the history (blame) for the respective\n>> man pages to see when the man page was initially committed, and when\n>> appropriate options were added.\n>>\n>> Maybe use one of the hosting providers GUI if that is your choice e.g.\n>> https://github.com/git/git/blame/master/Documentation/git-gc.txt\n> I got an impression that blame/log is an overkill for the request,\n> which asks for \"what tagged version?\", to which the answer would be\n> to compare the manual pages for each release (or scan the release\n> notes), perhaps?\n>\n>\n\nI was also concerned as to which way the problem was being addressed: \nwas it a need for a cross reference table for all commands, or was it \nfor just a select few?\n\nFor me, who likes a good UI, I found the GitHub blame UI quite useful \nwhen looking at files from the latter direction. It was much easier to \nscan the blame for the command's documentation page than try and scan \nthrough the endless release notes. Obviously this does expect that our \ndocumentation is fairly complete, at least at the 'mention an option' \nlevel, even if the occasional nuance didn't reach the docs.\n\n\nI can see that a cli terminal representation is likely to be harder to \nscan, and that some hosters don't provide a blame page, so it would be a \n'horses for courses' choice.\n\nPhilip\n"},{"id":"455768","messageId":"220523.861qwkz8kp.gmgdl@evledraar.gmail.com","threadId":"57911","inReplyTo":"3067d8e3-15a7-75fc-20d7-90de0fc3fee6@iee.email","subject":"Re: Git commands version documentation","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-05-23T13:08:43Z","receivedAt":"2022-05-23T13:23:51Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, May 23 2022, Philip Oakley wrote:\n\n> Hi Junio,\n>\n> On 23/05/2022 00:35, Junio C Hamano wrote:\n>> Philip Oakley <philipoakley@iee.email> writes:\n>>\n>>> One manual method is to look at the history (blame) for the respective\n>>> man pages to see when the man page was initially committed, and when\n>>> appropriate options were added.\n>>>\n>>> Maybe use one of the hosting providers GUI if that is your choice e.g.\n>>> https://github.com/git/git/blame/master/Documentation/git-gc.txt\n>> I got an impression that blame/log is an overkill for the request,\n>> which asks for \"what tagged version?\", to which the answer would be\n>> to compare the manual pages for each release (or scan the release\n>> notes), perhaps?\n>>\n>>\n>\n> I was also concerned as to which way the problem was being addressed:\n> was it a need for a cross reference table for all commands, or was it \n> for just a select few?\n>\n> For me, who likes a good UI, I found the GitHub blame UI quite useful\n> when looking at files from the latter direction. It was much easier to \n> scan the blame for the command's documentation page than try and scan\n> through the endless release notes. Obviously this does expect that our \n> documentation is fairly complete, at least at the 'mention an option'\n> level, even if the occasional nuance didn't reach the docs.\n>\n>\n> I can see that a cli terminal representation is likely to be harder to\n> scan, and that some hosters don't provide a blame page, so it would be\n> a 'horses for courses' choice.\n\nI think asking a git user to use \"git blame\" on our own source code is a\nnon-starter in terms of where we'd like to eventually get. It's not very\nfriendly, especially in the case of something like the log-family where\noption parsing is implemented over more than one file.\n\nLikewise some built-ins don't map to builtin/<name>.c, and all that is\nassuming a lot about the user knowing where to look.\n\nI think what the OP here really would like is something similar to\nPerl's \"corelist(1)\" but for Git. I.e. a meta-command you can ask to\ntell you what version introduced a given git sub-command, or even option\nfor that command etc.\n\nAlternatively (or perhaps in addition to that) we could aim to document\nthis sort of thing, e.g. have an \"INTRODUCED IN\" section or similar in\nthe command documentation, or a similar blurb when we discuss various\noptions.\n\nI have tried to add these sorts of mentions for some past changes,\ne.g. the \"<refspec>\" section in git-fetch(1) is one example (search for\n\"Git version 2.20\").\n\nI think we could do with more of that sort of thing. One difficulty with\ndoing this in git in particular is that (moreso than most other\nprojects) when you submit a patch you can't be very certain about what\nrelease it's going to be in, i.e. it might end up cooking for many weeks\n& past a release window.\n\nBut in any case, I think adding this as a first-class feature (perhaps\nto \"git help\") would be very useful, and it could be done in some way\nthat wouldn't be a pain to maintain.\n\nE.g. we could carry a text file in our sources with a list of what\ncommands existed at what versions, and what options they had (as\nextracted from the parse-options reflection mechanism). Rather than\nmanually maintain such a list we could carry a script to that would\nattempt to build past releases, for any that were missing we'd attempt\nto build them and fill in the gaps.\n\nWe could thus make this something (if Junio were willing) that would be\na relatively small addition to pre-release preparations.\n\nFor releases that couldn't be built anymore we could either manually\nfill in the data, or just not care. What exact version older than 1.8\nintroduced some command or option is something probably nobody cares\nabout at this point.\n\nBut it is *really useful* when scripting against git to know what\nrecent-ish release something was introduced in, especially so if we'd\nhelpfully annotate which releases were known to have been part of major\ndistro releases, such as RHEL major releases, or OSX's Apple Git etc.\n"},{"id":"455785","messageId":"96cd59ea-ea75-e33e-758f-abe16f9cca0f@iee.email","threadId":"57911","inReplyTo":"220523.861qwkz8kp.gmgdl@evledraar.gmail.com","subject":"Re: Git commands version documentation","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2022-05-23T15:19:31Z","receivedAt":"2022-05-23T15:19:37Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"Hi Ævar\n\nOn 23/05/2022 14:08, Ævar Arnfjörð Bjarmason wrote:\n> On Mon, May 23 2022, Philip Oakley wrote:\n>\n>> Hi Junio,\n>>\n>> On 23/05/2022 00:35, Junio C Hamano wrote:\n>>> Philip Oakley <philipoakley@iee.email> writes:\n>>>\n>>>> One manual method is to look at the history (blame) for the respective\n>>>> man pages to see when the man page was initially committed, and when\n>>>> appropriate options were added.\n>>>>\n>>>> Maybe use one of the hosting providers GUI if that is your choice e.g.\n>>>> https://github.com/git/git/blame/master/Documentation/git-gc.txt\n>>> I got an impression that blame/log is an overkill for the request,\n>>> which asks for \"what tagged version?\", to which the answer would be\n>>> to compare the manual pages for each release (or scan the release\n>>> notes), perhaps?\n>>>\n>>>\n>> I was also concerned as to which way the problem was being addressed:\n>> was it a need for a cross reference table for all commands, or was it \n>> for just a select few?\n>>\n>> For me, who likes a good UI, I found the GitHub blame UI quite useful\n>> when looking at files from the latter direction. It was much easier to \n>> scan the blame for the command's documentation page than try and scan\n>> through the endless release notes. Obviously this does expect that our \n>> documentation is fairly complete, at least at the 'mention an option'\n>> level, even if the occasional nuance didn't reach the docs.\n>>\n>>\n>> I can see that a cli terminal representation is likely to be harder to\n>> scan, and that some hosters don't provide a blame page, so it would be\n>> a 'horses for courses' choice.\n> I think asking a git user to use \"git blame\" on our own source code is a\n> non-starter in terms of where we'd like to eventually get. \n\n\"we?\"\n> It's not very\n> friendly, especially in the case of something like the log-family where\n> option parsing is implemented over more than one file.\n\nI think you've picked up the wrong essence of my answer, which was to\nHrushikesh's question that asked \"how could _they_ find out when various\n_particular_ maintenance commands (and by implication some options) were\nreleased?\". It wasn't any all-singing all-dancing solution to some other\nproblem, as I understood it.\n>\n> Likewise some built-ins don't map to builtin/<name>.c, and all that is\n> assuming a lot about the user knowing where to look.\n>\n> I think what the OP here really would like is something similar to\n> Perl's \"corelist(1)\" but for Git. I.e. a meta-command you can ask to\n> tell you what version introduced a given git sub-command, or even option\n> for that command etc.\n\ncorelist(1) is not something I'm familiar with, but looks like it might form the basis for a discussion about such a UX interface.\n\n>\n> Alternatively (or perhaps in addition to that) we could aim to document\n> this sort of thing, e.g. have an \"INTRODUCED IN\" section or similar in\n> the command documentation, or a similar blurb when we discuss various\n> options.\n>\n> I have tried to add these sorts of mentions for some past changes,\n> e.g. the \"<refspec>\" section in git-fetch(1) is one example (search for\n> \"Git version 2.20\").\n>\n> I think we could do with more of that sort of thing. One difficulty with\n> doing this in git in particular is that (moreso than most other\n> projects) when you submit a patch you can't be very certain about what\n> release it's going to be in, i.e. it might end up cooking for many weeks\n> & past a release window.\n>\n> But in any case, I think adding this as a first-class feature (perhaps\n> to \"git help\") would be very useful, and it could be done in some way\n> that wouldn't be a pain to maintain.\n\nThat \"wouldn't be a pain to maintain\" is probably the core of any such\ndesign..\n>\n> E.g. we could carry a text file in our sources with a list of what\n> commands existed at what versions, and what options they had (as\n> extracted from the parse-options reflection mechanism). Rather than\n> manually maintain such a list we could carry a script to that would\n> attempt to build past releases, for any that were missing we'd attempt\n> to build them and fill in the gaps.\n\nImplicit in this is the choice between parsing the code, or the\ndocumentation, to determine when options started appearing.\n>\n> We could thus make this something (if Junio were willing) that would be\n> a relatively small addition to pre-release preparations.\n>\n> For releases that couldn't be built anymore we could either manually\n> fill in the data, or just not care. What exact version older than 1.8\n> introduced some command or option is something probably nobody cares\n> about at this point.\n>\n> But it is *really useful* when scripting against git to know what\n> recent-ish release something was introduced in, especially so if we'd\n> helpfully annotate which releases were known to have been part of major\n> distro releases, such as RHEL major releases, or OSX's Apple Git etc.\nIn some ways it sounds very similar to the i18n efforts where the\n'database' grows with every release. Though capturing the historic\nrelease progression is probably the hardest part.\n\n--\nPhilip\n\n\n"},{"id":"455799","messageId":"220523.86o7zoxgzo.gmgdl@evledraar.gmail.com","threadId":"57911","inReplyTo":"96cd59ea-ea75-e33e-758f-abe16f9cca0f@iee.email","subject":"Re: Git commands version documentation","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-05-23T18:01:48Z","receivedAt":"2022-05-23T18:30:51Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, May 23 2022, Philip Oakley wrote:\n\n> Hi Ævar\n>\n> On 23/05/2022 14:08, Ævar Arnfjörð Bjarmason wrote:\n>> On Mon, May 23 2022, Philip Oakley wrote:\n>>\n>>> Hi Junio,\n>>>\n>>> On 23/05/2022 00:35, Junio C Hamano wrote:\n>>>> Philip Oakley <philipoakley@iee.email> writes:\n>>>>\n>>>>> One manual method is to look at the history (blame) for the respective\n>>>>> man pages to see when the man page was initially committed, and when\n>>>>> appropriate options were added.\n>>>>>\n>>>>> Maybe use one of the hosting providers GUI if that is your choice e.g.\n>>>>> https://github.com/git/git/blame/master/Documentation/git-gc.txt\n>>>> I got an impression that blame/log is an overkill for the request,\n>>>> which asks for \"what tagged version?\", to which the answer would be\n>>>> to compare the manual pages for each release (or scan the release\n>>>> notes), perhaps?\n>>>>\n>>>>\n>>> I was also concerned as to which way the problem was being addressed:\n>>> was it a need for a cross reference table for all commands, or was it \n>>> for just a select few?\n>>>\n>>> For me, who likes a good UI, I found the GitHub blame UI quite useful\n>>> when looking at files from the latter direction. It was much easier to \n>>> scan the blame for the command's documentation page than try and scan\n>>> through the endless release notes. Obviously this does expect that our \n>>> documentation is fairly complete, at least at the 'mention an option'\n>>> level, even if the occasional nuance didn't reach the docs.\n>>>\n>>>\n>>> I can see that a cli terminal representation is likely to be harder to\n>>> scan, and that some hosters don't provide a blame page, so it would be\n>>> a 'horses for courses' choice.\n>> I think asking a git user to use \"git blame\" on our own source code is a\n>> non-starter in terms of where we'd like to eventually get. \n>\n> \"we?\"\n\nWe as a project.\n\n>> E.g. we could carry a text file in our sources with a list of what\n>> commands existed at what versions, and what options they had (as\n>> extracted from the parse-options reflection mechanism). Rather than\n>> manually maintain such a list we could carry a script to that would\n>> attempt to build past releases, for any that were missing we'd attempt\n>> to build them and fill in the gaps.\n>\n> Implicit in this is the choice between parsing the code, or the\n> documentation, to determine when options started appearing.\n\nBy \"extracted from the parse-options reflection\" I mean that you could\nscript this around the same facility we use to dump what options we\nsupport for the bash completion.\n\nSee parse-options.c, all users of the API support a hidden option to\ndump their supported options, and likewise git.c can dump built-ins and\nother known lists of commands.\n\nSo in theory this sort of thing should be a relativel simple for-loop\nthat builds our release tags, for each successful builds lists the\nbuilt-ins, and for each of those lists the options.\n\nThe options being a bonus, it would already be useful if it just did\ncommand.\n\n> In some ways it sounds very similar to the i18n efforts where the\n> 'database' grows with every release. Though capturing the historic\n> release progression is probably the hardest part.\n\nAs long as we can still build that release it should be pretty easy...\n\n"}]}