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

Re: [PATCH v5 3/6] command-list.txt: group common commands by theme

From
Eric Sunshine <sunshine@sunshineco.com>
Date
May 11, 2015, 06:20 UTC
Message-ID
<CAPig+cSjdJ6Yhbvyw-m4E+Y9wEk71y0Cw2NO6c=f_cFy--YTGA@mail.gmail.com>
In-Reply-To
<1431191856-10949-4-git-send-email-sebastien.guimmara@gmail.com>

On Sat, May 9, 2015 at 1:17 PM, Sébastien Guimmara <sebastien.guimmara@gmail.com> wrote:

Show 12 quoted lines
> Declare groups for common commands in the [common] block,
> followed by group names and descriptions:
>
>     [common]
>     init         start a working area (see also: git help tutorial)
>     worktree     work on the current change (see also: git [...]
>     info         examine the history and state (see also: git [...]
>     history      grow, mark and tweak your history
>     remote       collaborate (see also: git help workflows)
>
> Some descriptions include a 'see also' to redirect user to more
> detailed documentation.

The example nicely shows the "see also", so this trailing sentence is somewhat redundant.

More below.
Show 22 quoted lines
> Then, in the [commands] block, map all common commands with a group:
>
>     [commands]
>     git-add        mainporcelain     worktree
>     git-branch     mainporcelain     history
>     git-checkout   mainporcelain     history
>     [...]
>
> So that 'git help' outputs those commands in headered groups.
>
> Helped-by: Junio C Hamano <gitster@pobox.com>
> Helped-by:  Emma Jane Hogbin Westby <emma.westby@gmail.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---
> diff --git a/command-list.txt b/command-list.txt
> index f1eae08..7e7ce53 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,29 +1,41 @@
> +# common commands are grouped by themes
> +# this order is the same that output by 'git help'
> +# map each common commands in the [commands] list to one of the groups.
Grammar: "map each common command"
Maybe also "one of these groups".
> +# a command should not be marked both [deprecated] and [common]

I wonder if it is really necessary to state this, as there is no technical reason for the restriction, and it should be common sense (one would hope).

Show 11 quoted lines
> +[common]
> +init         start a working area (see also: git help tutorial)
> +worktree     work on the current change (see also: git help everyday)
> +info         examine the history and state (see also: git help revisions)
> +history      grow, mark and tweak your history
> +remote       collaborate (see also: git help workflows)
> +
>  # List of known git commands.
> -# command name                         category [deprecated] [common]
> -git-add                                 mainporcelain common
> +# command name         [deprecated]     category                [common]
Why did [deprecated] move from following "category" to preceding it?

Also, I wonder if [common] should be spelled [<common>] or something to distinguish it from [deprecated] which is a literal token. (I don't care strongly; I'm just wondering.)

Show 140 quoted lines
> +[commands]
> +git-add                                 mainporcelain           worktree
>  git-am                                  mainporcelain
>  git-annotate                            ancillaryinterrogators
>  git-apply                               plumbingmanipulators
>  git-archimport                          foreignscminterface
>  git-archive                             mainporcelain
> -git-bisect                              mainporcelain common
> +git-bisect                              mainporcelain           info
>  git-blame                               ancillaryinterrogators
> -git-branch                              mainporcelain common
> +git-branch                              mainporcelain           history
>  git-bundle                              mainporcelain
>  git-cat-file                            plumbinginterrogators
>  git-check-attr                          purehelpers
>  git-check-ignore                        purehelpers
>  git-check-mailmap                       purehelpers
> -git-checkout                            mainporcelain common
> +git-checkout                            mainporcelain           history
>  git-checkout-index                      plumbingmanipulators
>  git-check-ref-format                    purehelpers
>  git-cherry                              ancillaryinterrogators
>  git-cherry-pick                         mainporcelain
>  git-citool                              mainporcelain
>  git-clean                               mainporcelain
> -git-clone                               mainporcelain common
> +git-clone                               mainporcelain           init
>  git-column                              purehelpers
> -git-commit                              mainporcelain common
> +git-commit                              mainporcelain           history
>  git-commit-tree                         plumbingmanipulators
>  git-config                              ancillarymanipulators
>  git-count-objects                       ancillaryinterrogators
> @@ -35,14 +47,14 @@ git-cvsimport                           foreignscminterface
>  git-cvsserver                           foreignscminterface
>  git-daemon                              synchingrepositories
>  git-describe                            mainporcelain
> -git-diff                                mainporcelain common
> +git-diff                                mainporcelain           history
>  git-diff-files                          plumbinginterrogators
>  git-diff-index                          plumbinginterrogators
>  git-diff-tree                           plumbinginterrogators
>  git-difftool                            ancillaryinterrogators
>  git-fast-export                                ancillarymanipulators
>  git-fast-import                                ancillarymanipulators
> -git-fetch                               mainporcelain common
> +git-fetch                               mainporcelain           remote
>  git-fetch-pack                          synchingrepositories
>  git-filter-branch                       ancillarymanipulators
>  git-fmt-merge-msg                       purehelpers
> @@ -51,7 +63,7 @@ git-format-patch                        mainporcelain
>  git-fsck                               ancillaryinterrogators
>  git-gc                                  mainporcelain
>  git-get-tar-commit-id                   ancillaryinterrogators
> -git-grep                                mainporcelain common
> +git-grep                                mainporcelain           info
>  git-gui                                 mainporcelain
>  git-hash-object                         plumbingmanipulators
>  git-help                               ancillaryinterrogators
> @@ -60,17 +72,17 @@ git-http-fetch                          synchelpers
>  git-http-push                           synchelpers
>  git-imap-send                           foreignscminterface
>  git-index-pack                          plumbingmanipulators
> -git-init                                mainporcelain common
> +git-init                                mainporcelain           init
>  git-instaweb                            ancillaryinterrogators
>  git-interpret-trailers                  purehelpers
>  gitk                                    mainporcelain
> -git-log                                 mainporcelain common
> +git-log                                 mainporcelain           info
>  git-ls-files                            plumbinginterrogators
>  git-ls-remote                           plumbinginterrogators
>  git-ls-tree                             plumbinginterrogators
>  git-mailinfo                            purehelpers
>  git-mailsplit                           purehelpers
> -git-merge                               mainporcelain common
> +git-merge                               mainporcelain           history
>  git-merge-base                          plumbinginterrogators
>  git-merge-file                          plumbingmanipulators
>  git-merge-index                         plumbingmanipulators
> @@ -79,7 +91,7 @@ git-mergetool                           ancillarymanipulators
>  git-merge-tree                          ancillaryinterrogators
>  git-mktag                               plumbingmanipulators
>  git-mktree                              plumbingmanipulators
> -git-mv                                  mainporcelain common
> +git-mv                                  mainporcelain           worktree
>  git-name-rev                            plumbinginterrogators
>  git-notes                               mainporcelain
>  git-p4                                  foreignscminterface
> @@ -90,11 +102,11 @@ git-parse-remote                        synchelpers
>  git-patch-id                            purehelpers
>  git-prune                               ancillarymanipulators
>  git-prune-packed                        plumbingmanipulators
> -git-pull                                mainporcelain common
> -git-push                                mainporcelain common
> +git-pull                                mainporcelain           remote
> +git-push                                mainporcelain           remote
>  git-quiltimport                         foreignscminterface
>  git-read-tree                           plumbingmanipulators
> -git-rebase                              mainporcelain common
> +git-rebase                              mainporcelain           history
>  git-receive-pack                        synchelpers
>  git-reflog                              ancillarymanipulators
>  git-relink                              ancillarymanipulators
> @@ -103,28 +115,28 @@ git-repack                              ancillarymanipulators
>  git-replace                             ancillarymanipulators
>  git-request-pull                        foreignscminterface
>  git-rerere                              ancillaryinterrogators
> -git-reset                               mainporcelain common
> +git-reset                               mainporcelain           worktree
>  git-revert                              mainporcelain
>  git-rev-list                            plumbinginterrogators
>  git-rev-parse                           ancillaryinterrogators
> -git-rm                                  mainporcelain common
> +git-rm                                  mainporcelain           worktree
>  git-send-email                          foreignscminterface
>  git-send-pack                           synchingrepositories
>  git-shell                               synchelpers
>  git-shortlog                            mainporcelain
> -git-show                                mainporcelain common
> +git-show                                mainporcelain           info
>  git-show-branch                         ancillaryinterrogators
>  git-show-index                          plumbinginterrogators
>  git-show-ref                            plumbinginterrogators
>  git-sh-i18n                             purehelpers
>  git-sh-setup                            purehelpers
>  git-stash                               mainporcelain
> -git-status                              mainporcelain common
> +git-status                              mainporcelain           info
>  git-stripspace                          purehelpers
>  git-submodule                           mainporcelain
>  git-svn                                 foreignscminterface
>  git-symbolic-ref                        plumbingmanipulators
> -git-tag                                 mainporcelain common
> +git-tag                                 mainporcelain           history
>  git-unpack-file                         plumbinginterrogators
>  git-unpack-objects                      plumbingmanipulators
>  git-update-index                        plumbingmanipulators
> --
> 2.4.0
Previous: Sébastien GuimmaraNext: Sébastien Guimmara
Message 7 of 14 in “git help: group common commands by theme”
  1. 0/6 git help: group common commands by themeSébastien Guimmara, May 9, 2015
  2. 1/6 generate-cmdlist: parse common group commandsSébastien Guimmara, May 9, 2015
  3. Eric SunshineMay 11, 2015
  4. 2/6 help.c: output the typical Git workflowSébastien Guimmara, May 9, 2015
  5. Eric SunshineMay 11, 2015
  6. 3/6 command-list.txt: group common commands by themeSébastien Guimmara, May 9, 2015
  7. Eric SunshineMay 11, 2015
  8. 4/6 Makefile: update to new command-list.txt formatSébastien Guimmara, May 9, 2015
  9. Eric SunshineMay 11, 2015
  10. 5/6 new-command.txt: mention the common command groupsSébastien Guimmara, May 9, 2015
  11. Eric SunshineMay 11, 2015
  12. 6/6 cmd-list.perl: ignore all lines until [commands]Sébastien Guimmara, May 9, 2015
  13. Eric SunshineMay 11, 2015
  14. Eric SunshineMay 11, 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.