From: Tian Yuchen <cat@malon.dev>
Date: Wed, 11 Mar 2026 04:33:31 GMT
Subject: Re: [PATCH v1] diff: document -U without <n> as using default context
Message-ID: <9fc9fb8b-5f91-4670-a674-76774c31d228@malon.dev>
In-Reply-To: <5973423.DvuYhMxLoT@piment-oiseau>

On 3/11/26 01:31, Jean-Noël AVILA wrote:

> In this case, isn't the long option also changed to optional number, such as:
> 
> `--unified[=<n>]`
> 
> ?

Indeed. Your statement aligns with what Junio said earlier.

>> The documentation for '-U<n>' implies that the numeric value '<n>' is
>> mandatory. However, the command line parser has historically accepted
>> '-U' without a number.
>>
>> Strictly requiring a number for '-U' would break existing tests
>> (e.g., in 't4013') and likely disrupt user scripts relying on this
>> undocumented behavior.
>>
>> Since we are retaining this fallback behavior for backward compatibility,
>> update the documentation to explicitly state that '<n>' can be omitted
>> for the short option '-U'.
>>
>> Signed-off-by: Tian Yuchen <cat@malon.dev>
>> ---
>>  Documentation/diff-context-options.adoc | 2 +-
>>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> I am moderately nagative.
> 
> It is not like we are _encouraging_ users to omit <n> from -U<n>,
> but it is not errored out only due to a bug.  Who would the new text
> help?  Users would wonder why <n> is not optional in --unified=<n>,
> the other way to spell the same thing.
> 
> If we want to be explicit, we should probably do this instead:
> 
>     `-U<n>`::
>     `--unified=<n>`::
>             Generate diffs with _<n>_ lines of context. Defaults to `diff.context`
>             or 3 if the config option is unset (`-U` without '<n>' is accepted
>             as a silent synonym for `-p` due to a historical accident).
> 
> which would tell readers what happens when '<n>' is omitted and why
> we allow such an inconsistency.

I have already fixed this in the v3 patch.

Thank you,

Yuchen