Re: [PATCH v1] diff: document -U without <n> as using default context

From: Tian Yuchen <cat@malon.dev>
Date: Mar 10, 2026, 04:51 UTC
Message-ID: <71287f25-eb60-4a45-b4ac-9368053c9183@malon.dev>
In-Reply-To: <xmqqwlzk1wd8.fsf@gitster.g>

Hi Junio,

Show 6 quoted lines

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

Show 10 quoted lines

> 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