git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Sébastien Guimmara <sebastien.guimmara@gmail.com>
Date
May 14, 2015, 12:59 UTC
Message-ID
<1431608351-9413-7-git-send-email-sebastien.guimmara@gmail.com>
In-Reply-To
<1431608351-9413-1-git-send-email-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:

Show 7 quoted lines
> 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

Previous: Sébastien GuimmaraNext: Junio C Hamano
Message 10 of 12 in “git help: group common commands by theme”
  1. 0/5 git help: group common commands by themeSébastien Guimmara, May 14, 2015
  2. 1/5 command-list.txt: prepare with [commands] headerSébastien Guimmara, May 14, 2015
  3. 2/5 command-list.txt: add with [common] blockSébastien Guimmara, May 14, 2015
  4. 3/5 generate-cmdlist: parse common group commandsSébastien Guimmara, May 14, 2015
  5. Junio C HamanoMay 14, 2015
  6. Eric SunshineMay 14, 2015
  7. Sébastien GuimmaraMay 15, 2015
  8. 4/5 command-list.txt: drop the common- prefixSébastien Guimmara, May 14, 2015
  9. 5/5 help.c: output the typical Git workflowSébastien Guimmara, May 14, 2015
  10. 5/5 help.c: output the typical Git workflowSébastien Guimmara, May 14, 2015
  11. Junio C HamanoMay 14, 2015
  12. Sébastien GuimmaraMay 15, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.