Re: [PATCH v9 2/5] command-list.txt: add the common groups block

["Sébastien Guimmara" <sebastien.guimmara@gmail.com>]

On 05/20/2015 09:48 PM, Eric Sunshine wrote:
> On Wed, May 20, 2015 at 3:22 PM, Sébastien Guimmara
> <sebastien.guimmara@gmail.com> wrote:
>> The ultimate goal is for "git help" to display common commands in
>> groups rather than alphabetically. As a first step, define the
>> groups in a new block, and then assign a group to each
>> common command.
>>
>> Add a block at the beginning of command-list.txt:
>>
>>      init         start a working area (see also: git help tutorial)
>>      worktree     work on the current change (see also:[...]
>>      info         examine the history and state (see also: git [...]
>>      history      grow, mark and tweak your history
>>      remote       collaborate (see also: git help workflows)
>>
>> storing information about common commands group, then map each common
>> command to a group:
>>
>>      git-add          mainporcelain        common worktree
>>
>> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
>> ---
>>   command-list.txt | 50 ++++++++++++++++++++++++++++++--------------------
>>   1 file changed, 30 insertions(+), 20 deletions(-)
>
> Hmm, did your update to Documentation/technical/new-command.txt get
> lost? I don't see it any of the patches, but would have expected it to
> be included in this patch which introduces the "common groups"
> section.
>

Ah, you're right. A commit got lost in the process. Will fix that. Thanks.

>> diff --git a/command-list.txt b/command-list.txt
>> index 609b344..c2bbdc1 100644
>> --- a/command-list.txt
>> +++ b/command-list.txt
>> @@ -1,3 +1,13 @@
>> +# common commands are grouped by themes output by 'git help'
>> +# map each common command in the command list to one of these groups.
>
> Discussed previously: It also would be a good idea to mention that the
> order in which "git help" displays the groups themselves is the order
> they are declared here. Maybe just add one more line between the two
> you already have above:
>
>      # groups are output by 'git help' in the order declared here.
>

Indeed, I'll add the mention.

>> +### common groups
>
> In the block below, the "### command list" line is protected by a "#
> do not molest the next line" warning. Perhaps the same should be done
> here? Alternately, make them more compact by incorporating the
> warning:
>
>      ### common groups (do not change this line)
>      ...
>      ### command list (do not change this line)
>
> ?
>

Yes, it's better. I shall modify this.

>> +init         start a working area (see also: git help tutorial)
>> +worktree     work on the current change (see also: git help everyday)
>> +info         examine the history and state (see also: git help revisions)
>> +history      grow, mark and tweak your common history
>> +remote       collaborate (see also: git help workflows)
>> +
>> +# List of known git commands.
>>   # do not molest the next line
>>   ### command list
>>   # command name                          category [deprecated] [common]