From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 09 Mar 2026 22:17:07 GMT
Subject: Re: [PATCH v1] diff: document -U without <n> as using default context
Message-ID: <xmqqwlzk1wd8.fsf@gitster.g>
In-Reply-To: <20260309172719.125419-1-cat@malon.dev>

Tian Yuchen <cat@malon.dev> writes:

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