From: Jeff Hostetler <git@jeffhostetler.com>
Date: Thu, 31 Jan 2019 22:33:29 GMT
Subject: Re: [PATCH v4 01/14] trace2: Documentation/technical/api-trace2.txt
Message-ID: <0384b5e0-e2e2-710f-2e37-1dff96aac143@jeffhostetler.com>
In-Reply-To: <20190131141127.GA10587@szeder.dev>



On 1/31/2019 9:11 AM, SZEDER Gábor wrote:
> On Wed, Jan 30, 2019 at 12:56:21PM -0800, Jeff Hostetler via GitGitGadget wrote:
>> From: Jeff Hostetler <jeffhost@microsoft.com>
> 
>> diff --git a/Documentation/technical/api-trace2.txt b/Documentation/technical/api-trace2.txt
> 
>> +== Public API
> 
>> +=== Command Detail Messages
>> +
>> +These are concerned with describing the specific Git command
>> +after the command line, config, and environment are inspected.
>> +
>> +`void trace2_cmd_verb(const char *command_verb)`::
>> +
>> +	Emits a "cmd_verb" message with the canonical name of
>> +	(usually) builtin command, for example "status" or "checkout".
>> +
>> +`void trace2_cmd_subverb(const char *command_subverb)`::
>> +
>> +	Emits a "cmd_subverb" message with a qualifier name to further
>> +	describe the current git command.
> 
> OK, so now we know what is meant by 'verb' and 'subverb'.
> 
> Alas, this explanation also clearly shows that the word 'verb' is a
> poor fit for what it tries to convey, and 'subverb' is even worse.

How can we resolve this?

I've been using the term "command" (1) to refer to the entire lifetime
of a git command (process/instance/invocation).  Trace2 issues a series
of trace messages over that life of the process that all have a unique
id.  This allows multiple concurrent processes to write to the same
file and yet be able to associate all of the messages from a single
command instance.

I've been using the term "verb" (2) to the action -- i.e. "status" in
a "git status" command and "fetch" in a "git fetch" command.

I've been using the term "subverb" (3) to refer to the variant when
there are major differences.

What would be better choices for these 3 concepts?

Would something like "process", "command", and "mode" be better?
Or maybe "process", "command", and "command-mode"?

I'd rather not use the term "subcommand" because it already has mixed
usage.
[] See git_more_info_string[] in git.c and list_all_cmd_help()
    in help.c where both "command" and "subcommand" are used
    interchangeably.
[] And yet another completely different usage in git-submodule
    and bisect where "subcommand" is used to mean the 3rd token
    on the command line after the "command".

Suggestions?
Jeff