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

Sébastien Guimmara  [off-list ref] writes:

We could then display headers this way:

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 an existing one
    * examining the history and state:
      diff       Show changes between commits, commit and working tree, etc
      log        Show commit logs
      show       Show various types of objects
      status     Show the working tree status
      bisect     Find by binary search the change that introduced a bug
      grep       Print lines matching a pattern

   * working on the current change:
      add        Add file contents to the index
      checkout   Checkout a branch or paths to the working tree
      reset      Reset current HEAD to the specified state
      rm         Remove files from the working tree and from the index
      mv         Move or rename a file, a directory, or a symlink
    * growing, marking and tweaking your history:
      commit     Record changes to the repository
      rebase     Forward-port local commits to the updated upstream head
      tag        Create, list, delete or verify a tag object signed with GPG
    * working with others:
      fetch      Download objects and refs from another repository
      pull       Fetch from and integrate with another repository or a local branch
      push       Update remote refs along with associated objects
    * branching and merging histories:
      branch     List, create, or delete branches
      merge      Join two or more development histories together

This raises a few questions:

1. Is 'bisect' really a common command (from the target audience standpoint)

That is a good question, but so are many other commands.

I think that (1) it is a good idea to list commands in groups, (2)
having group-head is necessary if we list commands in groups, but
(3) because group-heads consume valuable vertical space in the
output, we may have to have fewer commands in the list.

For example, "mv" and "rm" are very questionable things to have in
the "most commonly used" list.  All you need to start with Git is
"add" and "commit -a".

"clone" and "init" are "once per working area for a project you deal
with" kind of thing, and cannot be in the "commonly used and you
benefit from a gentle nudge to read about it more in the manual to
learn Git" category by definition.

"rebase" should be with "merge" and "branch", but I wouldn't have
"branching and merging" as a separate category---they are all part
of "growing and tweaking".  And "branch" itself may be questionable
for those who are starting with Git.

Do we care about the ordering of the items within groups, by the way?

2. Does 'Forward-port local commits to the updated upstream head' really help
   to grok the idea of 'rebase' ? There are 3 words in this sentence that
   an unfamiliar git user may not be comfortable with...

"Rebuild the history on a branch on top of a new commit", perhaps?

But this brings us back to "what the target audience?" question.

My answer to the question has always been "the list is a gentle
nudge to guide the user to read about it more in the manual to
learn."  The sooner users are guided to graduate from the "not be
comfortable" state, the more productive they will be.

For that to happen, we would need to (1) strongly suggest that the
subcommand is what the user wants to use, and (2) carefully avoid
giving an impression that the user learned everything there is to
know in order to use the command effectively from that single line.

Of course, an argument can be made that the single-line should aim
to teach everything there is to know in order to use the command
effectively, but because I do not think that is feasible I would
aim for the second best, which is why we want to keep the last two
lines about "git help <command> for a specific subcommand".