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

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Mar 9, 2026, 22:00 UTC
Message-ID: <CALnO6CAJfton4KwywVeRFbynWH9zu4nY4c6uXOnEdddKtZpeqA@mail.gmail.com>
In-Reply-To: <20260309172719.125419-1-cat@malon.dev>

On Mon, Mar 9, 2026 at 1:28 PM Tian Yuchen <cat@malon.dev> wrote:

Show 30 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(-)
>
> diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc
> index e161260358..655496ec3a 100644
> --- a/Documentation/diff-context-options.adoc
> +++ b/Documentation/diff-context-options.adoc
> @@ -1,4 +1,4 @@
> -`-U<n>`::
> +`-U[<n>]`::
>  `--unified=<n>`::
>         Generate diffs with _<n>_ lines of context. Defaults to `diff.context`
>         or 3 if the config option is unset.
> --
> 2.43.0

I was curious about the way we indicate this kind of optionality for single-letter options, so:

    git grep -e '-[[:alnum:]]\[' Documentation

which finds many hits of this pattern. Cool. Adding -A1, we see that it is also common to document the long-form like

    --unified[=<n>]

which you may want to add to this patch. (I haven't really considered the rest of it very well, although it does seem worth updating the syntax to match what some of our tests exercise.)

Which makes me notice: 3 is the default if the config option is unset _or_ if <n> is not provided. Is there a better wording to indicate that? Maybe the simplest tweak is to clarify that <n> is the thing which defaults to… (since a first read might leave the reader wondering "what defaults to diff.context or 3? ah, it's probably n…"). But a glance at other docs makes this pattern seem common while some do say "if <n> is specified…", so idk.

BTW I noticed these docs are duplicated between Documentation/diff-{,context-}options.adoc

-- 
D. Ben Knoble