Re: [PATCH 0/3] git help: group common commands by theme

On 05/06/2015 05:08 AM, Eric Sunshine wrote:

On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
[off-list ref] wrote:

quoted

This v4 includes the following suggestions:

In command-list.txt:
- Add a [groups] block containing names and description for groups:

    [groups]
    init                   starting a working area
    worktree               working on the current change
    remote                 working with others
    info                   examining the history and state
    history                growing, marking and tweaking your history

- Add a [commands] header on top of the known command list, and
   group names as a third column.

    [commands]
    git-add            mainporcelain                common-worktree
    git-am             mainporcelain
    git-annotate       ancillaryinterrogators
    git-apply          plumbingmanipulators
    git-archimport     foreignscminterface
    git-archive        mainporcelain
    git-bisect         mainporcelain
    git-blame          ancillaryinterrogators
    git-branch         mainporcelain                common-history

Thanks, this version is looking better. I, personally, still find the
redundant "command-" prefix ugly and would just as soon see it go
away. I'll make some suggestions about that when reviewing patch 2/3.

Indeed, I'm a bit annoyed by this prefix. We could do two things:
- either drop the [deprecated] options, since it's never used.
- or keep it, but make it exclusive with [common]. It makes sense after
   all that if a command is deprecated, we don't want to consider it
   common anymore.

In both cases, we end up with only three columns, the third being
optional.

The common- prefix can then be removed in favor of the group ID alone.

quoted

I removed from the list of common commands: rebase, rm, mv, bisect
because [1] they are not really common to an unfamiliar user, [2] to
save vertical space occupied by group headers.

Please perform the removals in a separate (preparatory) patch. Not
only is it difficult to spot the removals mixed in with the primary
changes of 1/3, but they are not even mentioned in the commit message
of that patch. More generally, the removals are a logically distinct
change from assigning groupings to the common commands, thus deserve
their own patch.

Thanks. I will separate both patches.