Re: [PATCH] send-email: export patch counters in validate environment

[Junio C Hamano <gitster@pobox.com>]

Phillip Wood <phillip.wood123@gmail.com> writes:

> Hi Robin
>
> On 11/04/2023 12:47, Robin Jarry wrote:
>> When sending patch series (with a cover-letter or not)
>> sendemail-validate is called with every email/patch file independently
>> from the others. When one of the patches depends on a previous one, it
>> may not be possible to use this hook in a meaningful way. A hook that
>> wants to check some property of the whole series needs to know which
>> patch is the final one.
>> Expose the current and total number of patches to the hook via the
>> GIT_SENDEMAIL_PATCH_COUNTER and GIT_SENDEMAIL_PATCH_TOTAL environment
>> variables so that both incremental and global validation is possible.

The above mentions "cover letter" and naturally the readers would
wonder how it is treated.  When we have 5-patch series with a
separate cover letter, do we get TOTAL=6, COUNTER=1 for the cover,
COUNTER=2 for [PATCH 1/5], and so on, or do we see TOTAL=5,
COUNTER=0 for the cover, counter=1 for [PATCH 1/5], and so on?

The latter is certainly richer (with the former, the validator that
wants to act differently on the cover has to somehow figure out if
the invocation with COUNTER=1 is seeing the cover or the first
patch).  The usual and recommended workflow being "git format-patch
-o outdir --cover-letter <range>" followed by "edit outdir/*" to
proofread and edit the cover and the patches, followed by "git
send-email outdir/*.patch", git-send-email has to guess before
invoking the hook.

But it may be better than forcing the hook to guess, I dunno?

Whichever way we choose, we should

 * explain the choice in the proposed log message.  If we choose the
   "TOTAL is the number of patches and COUNTER=0 is used for the
   optional cover letter" interpretation, we should also explain
   that we cannot reliably do so and sometimes can guess wrong.  If
   we choose the "TOTAL is the number of input files and COUNTER
   just counts, regardless of the payload" interpretation, we should
   also explain that even though we hinted that a series with cover
   letter can be validated, it is a slight lie, because the hook has
   to guess if the series has cover and it can guess wrong.

 * document what TOTAL and COUNTER means.

>> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt
>> index 62908602e7be..55f00e0f6f8c 100644
>> --- a/Documentation/githooks.txt
>> +++ b/Documentation/githooks.txt
>> @@ -600,6 +600,16 @@ the name of the file that holds the e-mail to be sent.  Exiting with a
>>   non-zero status causes `git send-email` to abort before sending any
>>   e-mails.
>>   +The following environment variables are set when executing the
>> hook.
>> +
>> +`GIT_SENDEMAIL_PATCH_COUNTER`::
>> +	A 1-based counter incremented by one for every file.
>> +
>> +`GIT_SENDEMAIL_PATCH_TOTAL`::
>> +	The total number of files.
>> +
>> +These variables can be used to validate patch series.

This may be sufficient documentation to imply we are not treating
cover letter any differently, by not saying "patch" or "cover
letter" but just saying "file".  It may be more helpful to be a bit
more explicit, though (e.g. "files" -> "input files", perhaps).

>>   diff --git a/git-send-email.perl b/git-send-email.perl
>> index 07f2a0cbeaad..e962d5e15983 100755
>> --- a/git-send-email.perl
>> +++ b/git-send-email.perl
>> @@ -795,10 +795,17 @@ sub is_format_patch_arg {
>>   @files = handle_backup_files(@files);
>>     if ($validate) {
>> +	my $num = 1;
>> +	my $num_patches = @files;
>>   	foreach my $f (@files) {
>>   		unless (-p $f) {
>> +			$ENV{GIT_SENDEMAIL_PATCH_COUNTER} = "$num";
>> +			$ENV{GIT_SENDEMAIL_PATCH_TOTAL} = "$num_patches";
>
> We only need to set this once outside the loop

Indeed.

>>   			validate_patch($f, $target_xfer_encoding);
>> +			delete $ENV{GIT_SENDEMAIL_PATCH_COUNTER};
>> +			delete $ENV{GIT_SENDEMAIL_PATCH_TOTAL};
>
> Do we really need to clear these? Certainly not in each iteration of
> the loop I would think.

If we set TOTAL outside, we should clear it outside.  We have to set
COUNTER inside, and we could clear it outside, but it probably is
easier to see the correspondence of set/clear if it is done inside.

>>   		}
>> +		$num += 1;

When you have 3 files to send, and if the last one satisfies "-p",
the hook will be told "You are called for 1/3" and then "2/3", and
will never hear about "3/3", so in practice it will spool the first
two and finish without getting a chance to flush what has been
spooled.  When you have 3 files to send, and if the first one
satisfies "-p', the hook will be told "You are called for 2/3", but
it is understandable if anybody is tempted to write a hook this way:

	if COUNTER==1:
		initialize the spool area
		record TOTAL there
	else:
		read TOTAL recorded in the spool area
		make sure TOTAL matches

	process [PATCH COUNTER/TOTAL] individually
	if COUNTER==TOTAL:
		process the series as a whole

and for such an invocation of "git send-email", the hook will try to
process the second file without having its state fully initialzied
because it never saw the first.

Would these be problems?  I dunno.

Thanks for working on the patch, and thanks for a careful review.