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

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

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.

More below.

This produces the following output of $ git help:

[...]
The most commonly used git commands are:

   * starting a working area:
      clone      Clone a repository into a new directory
      init       Create an empty Git repository or reinitialize [...]

   * working on the current change:
      add        Add file contents to the index
      reset      Reset current HEAD to the specified state

   * working with others:
      fetch      Download objects and refs from another repository
      pull       Fetch from and integrate with another repository [...]
      push       Update remote refs along with associated objects

   * examining the history and state:
      log        Show commit logs
      status     Show the working tree status

   * growing, marking and tweaking your history:
      branch     List, create, or delete branches
      checkout   Checkout a branch or paths to the working tree
      commit     Record changes to the repository
      diff       Show changes between commits, commit and working [...]
      merge      Join two or more development histories together
[...]

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.