From: Tian Yuchen <cat@malon.dev>
Date: Tue, 10 Mar 2026 04:51:23 GMT
Subject: Re: [PATCH v1] diff: document -U without <n> as using default context
Message-ID: <71287f25-eb60-4a45-b4ac-9368053c9183@malon.dev>
In-Reply-To: <xmqqwlzk1wd8.fsf@gitster.g>

Hi Junio,

> 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.

Indeed.

What I was actually thinking earlier was: for bugs like this, which most 
likely come from misoperations, typos, or inconsistencies from *ancient* 
standards, should we acknowledge them as

“yes it is a bug/historical issue”

or

“*special behavior* we defined”?

I'm not as familiar with the Git codebase as you are, so I couldn't make 
a definitive call. I chose the second approach, but I now agree the 
first makes more sense. In other words, users shouldn't be *encouraged* 
to engage in such behavior, right?

> 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.

That makes sense. I'll make the changes accordingly.

Regards,

Yuchen