Subject: Re: [PATCH v2 1/5] add-patch: improve help for options j, J, k, and K

From: René Scharfe <[email-masked]>
Date: Mon, 6 Oct 2025 19:17:53 +0200

On 10/5/25 11:30 PM, Junio C Hamano wrote:
> René Scharfe <[email-masked]> writes:
> 
>> The options j, J, k, and K don't affect the status of the current hunk.
>> They just go to a different one.  This is true whether the current hunk
>> is undecided or not.  Avoid misunderstanding by no longer mentioning
>> the current hunk explicitly in their help texts.
>>
>> Signed-off-by: René Scharfe <[email-masked]>
>> ---
>>  Documentation/git-add.adoc | 8 ++++----
>>  add-patch.c                | 8 ++++----
>>  2 files changed, 8 insertions(+), 8 deletions(-)
>>
>> diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc
>> index ad629c46c5..3266ccf105 100644
>> --- a/Documentation/git-add.adoc
>> +++ b/Documentation/git-add.adoc
>> @@ -342,10 +342,10 @@ patch::
>>         d - do not stage this hunk or any of the later hunks in the file
>>         g - select a hunk to go to
>>         / - search for a hunk matching the given regex
>> -       j - leave this hunk undecided, see next undecided hunk
>> -       J - leave this hunk undecided, see next hunk
>> -       k - leave this hunk undecided, see previous undecided hunk
>> -       K - leave this hunk undecided, see previous hunk
>> +       j - go to the next undecided hunk
>> +       J - go to the next hunk
>> +       k - go to the previous undecided hunk
>> +       K - go to the previous hunk
> 
> These obviously make sense, but I wonder if y/n should also say that
> they not just make a decision on the current hunk, but after doing
> so they move you forward

Yes.

> (and if so, that may fall within the theme
> of this step, which is to improve the help text on options).

I see it more narrowly: This patch removes unnecessary references to the
hunk's status, while a y/n doc patch would add missing pieces.

Hmm, would the help text need to adapt to whether the current hunk is
the last undecided one?  E.g., "stage this hunk, implies 'j'" if j is an
allowed option and "stage this hunk and quit" otherwise?  Stuff for a
separate series, I think.

René