Description
The Git suite option parsing API's Technical Documentation suggests this about the option descriptions of a (sub)command:
description
is a short string to describe the effect of the option.
It shall begin with a lower-case letter and a full stop (.
) shall be
omitted at the end.
A bit more insight about what exactly are the option descriptions (or rather what options are): Generally, a (sub)command has various options that may go with it, for instance, a popular one may be quiet
(--quiet
or -q
) which suppresses the output of an action performed by a (sub)command; another one may be verbose
(--verbose
or -v
) which gives a bit more detail about the actions being performed by the (sub)command. The job of the parse_options
API is to intake the arguments passed down via the command line and sieve out the options (if provided) and the non-option arguments (such as a branch
or a filename
), thus modifying the final argv[]
array to hold the non-option arguments leaving out the other arguments (such as the (sub)comand name, unless explicitly specified by the PARSE_OPT_KEEP_ARGV0
flag).
Whenever the user uses the (sub)command in a wrong manner (such as not providing a mandatory argument), the program exits with an error code prompting out a usage
which kinda looks like:
usage: git submodule--helper set-branch [--quiet] (-d|--default) <path>
or: git submodule--helper set-branch [--quiet] (-b|--branch) <branch> <path>
-q, --quiet suppress output for setting default tracking branch of a submodule
--default set the default tracking branch to master
--branch <branch> set the default tracking branch to the one specified
As one may observe above, there are two ways to use the subcommand set-branch
of git submodule
along with the options available to use along with it as well as their description. The options
array of the above case looks like:
struct option options[] = {
OPT__QUIET(&quiet, N_("suppress output for setting default tracking branch of a submodule")),
OPT_BOOL(0, "default", &opt_default, N_("set the default tracking branch to master")),
OPT_STRING(0, "branch", &opt_branch, N_("branch"), N_("set the default tracking branch to the one specified")),
OPT_END()
};
Now one can clearly observe where the description is above. Various (sub)commands' (such as here) option
arrays don't follow the guideline provided by the parse_options
Documentation regarding the descriptions. This needs to be amended.