[PATCH 5/5] help.c: output the typical Git workflow

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

From: Eric Sunshine <sunshine <at> sunshineco.com>
Subject: Re: [PATCH v5 0/6] git help: group common commands by theme
Newsgroups: gmane.comp.version-control.git
Date: 2015-05-11 05:52:50 GMT (1 day, 12 hours and 19 minutes ago)

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara
<sebastien.guimmara <at> gmail.com> wrote:
> Sébastien Guimmara (6):
>   generate-cmdlist: parse common group commands
>   help.c: output the typical Git workflow
>   command-list.txt: group common commands by theme
>   Makefile: update to new command-list.txt format
>   new-command.txt: mention the common command groups
>   cmd-list.perl: ignore all lines until [commands]

When preparing a patch series, it's important to think not just about
the final result but also the state of the project at any point within
the series. The project should remain in a working state (not broken
and not regressed) at all steps during the patch series[1]. As each
patch is applied, you should be able to build git successfully, and
run "git help" and get expected results (for that point in the
series). If you can't do either, then there is a problem.

Unfortunately, the organization of this series (v5) breaks the build
and raw functionality from the get-go. Here is a proposed organization
which will keep the project in a sane state as each patch is applied:

patch 1:

[x] Add a [commands] header to command-list.txt
[x] check-docs in Makefile, and either
[x] cmd-list.perl to ignore everything up to and including [commands]. 

You're not actually doing any classification in
command-list.txt at this point, but instead merely preparing the
machinery to deal with the [commands] header (and the [common] section
which you will add in a subsequent patch).

patch 2:

[x] Add the [common] block to command-list.txt and tag each of
the common commands with an attribute from [common]. Do *not*,
however, remove the old "common" tag at this point since
generate-cmdlist.sh still needs it.

patch 3: 
[x] Introduce generate-cmdlist.awk and 
[x] retire generate-cmdlist.sh, 
[x] along with the associated Makefile changes. This
patch should be exactly the one I posted[2] (between the "--- >8 ---"
lines), along with the minor fixup[3]. The changes in that patch are a
logical unit, so they shouldn't be split up (as you did in v5 between
patches 1/6 and 4/6).

patch 4: 
[x] Drop the old "common" attribute from command-list.txt items
since it's no longer needed by any machinery.

patch 5: Update help.c to group and sort the commands using the new
common_cmd_groups[] array and common_commands[].group field.

patch 6 [optional]: Update howto/new-command.txt. Alternately, and
probably preferably, fold this documentation update into patch 2 and
omit this step.

[1]: This is called "preserving bisectability". See "git bisect".
[2]: http://article.gmane.org/gmane.comp.version-control.git/268598
[3]: http://article.gmane.org/gmane.comp.version-control.git/268599