Skip to content

Amend usages of various (sub)commands #636

Open
@periperidip

Description

@periperidip

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions