From: Philip Oakley <philipoakley@iee.org>
Date: Sat, 12 May 2018 17:50:06 GMT
Subject: Re: [PATCH v6 11/13] command-list.txt: documentation and guide line
Message-ID: <E92D8A89AD3E49229B84F08DDE883ED8@PhilipOakley>
In-Reply-To: <20180507175222.12114-12-pclouds@gmail.com>

Hi Duy,

From: "Nguyễn Thái Ngọc Duy" <pclouds@gmail.com> : Monday, May 07, 2018
> This is intended to help anybody who needs to update command-list.txt.
> It gives a brief introduction of all attributes a command can take.
> ---
> command-list.txt | 44 ++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 44 insertions(+)
>
> diff --git a/command-list.txt b/command-list.txt
> index 99ddc231c1..9c70c69193 100644
> --- a/command-list.txt
> +++ b/command-list.txt
> @@ -1,3 +1,47 @@
> +# Command classification list
> +# ---------------------------
> +# All supported commands, builtin or external, must be described in
> +# here. This info is used to list commands in various places. Each
> +# command is on one line followed by one or more attributes.
> +#
> +# The first attribute group is mandatory and indicates the command
> +# type. This group includes:
> +#
> +#   mainporcelain
> +#   ancillarymanipulators
> +#   ancillaryinterrogators
> +#   foreignscminterface
> +#   plumbingmanipulators
> +#   plumbinginterrogators
> +#   synchingrepositories
> +#   synchelpers
> +#   purehelpers
> +#
> +# The type names are self explanatory. But if you want to see what
> +# command belongs to what group to get a better picture, have a look
> +# at "git" man page, "GIT COMMANDS" section.
> +#
> +# Commands of type mainporcelain can also optionally have one of these
> +# attributes:
> +#
> +#   init
> +#   worktree
> +#   info
> +#   history
> +#   remote
> +#
> +# These commands are considered "common" and will show up in "git
> +# help" output in groups. Uncommon porcelain commands must not
> +# specify any of these attributes.
> +#
> +# "complete" attribute is used to mark that the command should be
> +# completable by git-completion.bash. Note that by default,
> +# mainporcelain commands are completable so you don't need this
> +# attribute.
> +#
> +# While not true commands, guides are also specified here, which can
> +# only have "guide" attribute and nothing else.

While the file is called ~ "Command List", the list is here as a support to
the Help function, and ultimately to the user's reading of the man pages,
including the man(5/7) guides, so I'd view the man page guides as first
class citizens.

Perhaps:
# As part of the Git man page list, the man(5/7) guides are also specified
# here, which can only have "guide" attribute and nothing else.

--
Philip

> +#
> ### command list (do not change this line, also do not change alignment)
> # command name                          category [category] [category]
> git-add                                 mainporcelain           worktree
> -- 
> 2.17.0.705.g3525833791
>
>