Junio C Hamano <gitster@xxxxxxxxx> writes: > Instead of going over the patches in the rest of the series, I think > we'd probably need to step back a bit and give ourselves a general > guideline. Having said that, I am a bit torn on the next step. The updates done in this series stops way short to make the usage strings conform to the proposed guideline. We could include such changes to make them conform, but that would make the series that is already long even longer, which is not what I want to see. My preference is to go in the other direction, i.e. make NO attempt to improve usage strings in this series, the only change we will make would be, except for documenting the coding guideline and adding tests that ensure usage strings in the code and in the document match for majority of commands, are to make sure the code and the doc match (IOW, if an existing option is not described in either, we leave it to a later round to add it, as long as the code and the doc consistently fail to describe it). That may allow us to make this series shorter than it currently is, hopefully? I dunno. And a fix to the proposed guideline. > * The usage string for a command with a large number of options can > and should use "[<options>]" placeholder in the SYNOPSIS and > "usage:" lines, i.e. "git cmd [<options>]", and let the > DESCRIPTION section (in documentation) and the option listing (in > the output from usage_with_options() function). "... list and explain them" is missing from the end.
