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

[Junio C Hamano <gitster@pobox.com>]

Sébastien Guimmara  <sebastien.guimmara@gmail.com> 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".