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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 9, 2026, 22:17 UTC
Message-ID: <xmqqwlzk1wd8.fsf@gitster.g>
In-Reply-To: <20260309172719.125419-1-cat@malon.dev>

Tian Yuchen <cat@malon.dev> writes:

Show 16 quoted lines

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