{"thread":{"id":"65158","subject":"An annoying \"Bug\" that we would probably leave as-is","startedAt":"2026-03-06T23:10:36Z","lastAt":"2026-03-11T04:33:38Z","messageCount":14,"participants":["Junio C Hamano","Tian Yuchen","D. Ben Knoble","Oswald Buddenhagen","Jean-Noël AVILA"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"538135","messageId":"xmqqh5qswo45.fsf@gitster.g","threadId":"65158","inReplyTo":null,"subject":"An annoying \"Bug\" that we would probably leave as-is","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-06T23:10:34Z","receivedAt":"2026-03-06T23:10:36Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"git show -U\" does not complain.  In an ideal world, it should say\n\"-U wants a number\", just like \"git show -Unan\" does.\n\nUnfortunately t/t4013/ actually has tests that break if we start\ntightening the command line parser for this.\n\nThis falls into the \"if it hurts, do not do it\" category that\nsomebody might be taking advantage of out there that we might be\nbetter off leaving them broken.\n\n\n\n diff.c | 9 ++++-----\n 1 file changed, 4 insertions(+), 5 deletions(-)\n\ndiff --git c/diff.c w/diff.c\nindex a1961526c0..ff79a41cfc 100644\n--- c/diff.c\n+++ w/diff.c\n@@ -5581,15 +5581,14 @@ static int diff_opt_unified(const struct option *opt,\n \t\t\t    const char *arg, int unset)\n {\n \tstruct diff_options *options = opt->value;\n-\tchar *s;\n+\tchar *s = NULL;\n \n \tBUG_ON_OPT_NEG(unset);\n \n-\tif (arg) {\n+\tif (arg)\n \t\toptions->context = strtol(arg, &s, 10);\n-\t\tif (*s)\n-\t\t\treturn error(_(\"%s expects a numerical value\"), \"--unified\");\n-\t}\n+\tif (!s || *s)\n+\t\treturn error(_(\"%s expects a numerical value\"), \"--unified\");\n \tenable_patch_output(&options->output_format);\n \n \treturn 0;\n"},{"id":"538299","messageId":"8d0ca4db-3745-49fd-8373-2d3d71aeea78@gmail.com","threadId":"65158","inReplyTo":"xmqqh5qswo45.fsf@gitster.g","subject":"Re: An annoying \"Bug\" that we would probably leave as-is","fromName":"Tian Yuchen","fromEmail":"a3205153416@gmail.com","sentAt":"2026-03-09T17:10:01Z","receivedAt":"2026-03-09T17:10:07Z","isPatch":false,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"Hi Junio,\n\nOn 3/7/26 07:10, Junio C Hamano wrote:\n> \"git show -U\" does not complain.  In an ideal world, it should say\n> \"-U wants a number\", just like \"git show -Unan\" does.\n> \n> Unfortunately t/t4013/ actually has tests that break if we start\n> tightening the command line parser for this.\n> \n> This falls into the \"if it hurts, do not do it\" category that\n> somebody might be taking advantage of out there that we might be\n> better off leaving them broken.\n\nOut of curiosity, I applied your patch and ran t4013 to see exactly what \nwould break. It turns out it's 'not ok 157 - git diff -U initial..side'.\n\nThe suite explicitly relies on 'git diff -U' (without a number) to\nimplicitly default to 3 lines of context, behaving identically to '-u'.\nWith your patch, it correctly but fatally throws 'error: --unified\nexpects a numerical value' instead of generating the diff, causing the\ntest to fail.\n\nI looked at diff-context-options.adoc, and it says:\n\n`-U<n>`::\n`--unified=<n>`::\n\tGenerate diffs with _<n>_ lines of context. Defaults to `diff.context`\n\tor 3 if the config option is unset.\n\nI believe this description needs revision, as in actual practice (as you \ndescribed), the number following '-U' is not strictly required.\n\n(I was taken aback, especially when you mentioned “somebody might be \ntaking advantage of out there.” It made me realize how an inadvertent \nlittle bug or minor error can become a daily habit for many people, or \neven foundations of millions of scripts. Just a thought. ;)\n\nRegards,\n\nYuchen\n\n\n"},{"id":"538302","messageId":"20260309172719.125419-1-cat@malon.dev","threadId":"65158","inReplyTo":"xmqqh5qswo45.fsf@gitster.g","subject":"[PATCH v1] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-09T17:27:19Z","receivedAt":"2026-03-09T17:27:53Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"The documentation for '-U<n>' implies that the numeric value '<n>' is\nmandatory. However, the command line parser has historically accepted\n'-U' without a number.\n\nStrictly requiring a number for '-U' would break existing tests\n(e.g., in 't4013') and likely disrupt user scripts relying on this\nundocumented behavior.\n\nSince we are retaining this fallback behavior for backward compatibility,\nupdate the documentation to explicitly state that '<n>' can be omitted\nfor the short option '-U'.\n\nSigned-off-by: Tian Yuchen <cat@malon.dev>\n---\n Documentation/diff-context-options.adoc | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc\nindex e161260358..655496ec3a 100644\n--- a/Documentation/diff-context-options.adoc\n+++ b/Documentation/diff-context-options.adoc\n@@ -1,4 +1,4 @@\n-`-U<n>`::\n+`-U[<n>]`::\n `--unified=<n>`::\n \tGenerate diffs with _<n>_ lines of context. Defaults to `diff.context`\n \tor 3 if the config option is unset.\n-- \n2.43.0\n\n"},{"id":"538324","messageId":"CALnO6CAJfton4KwywVeRFbynWH9zu4nY4c6uXOnEdddKtZpeqA@mail.gmail.com","threadId":"65158","inReplyTo":"20260309172719.125419-1-cat@malon.dev","subject":"Re: [PATCH v1] diff: document -U without <n> as using default context","fromName":"D. Ben Knoble","fromEmail":"ben.knoble@gmail.com","sentAt":"2026-03-09T22:00:52Z","receivedAt":"2026-03-09T22:01:06Z","isPatch":true,"sender":{"key":"ben.knoble@gmail.com","avatar":"https://avatars.githubusercontent.com/u/22802209?v=4"},"body":"On Mon, Mar 9, 2026 at 1:28 PM Tian Yuchen <cat@malon.dev> wrote:\n>\n> The documentation for '-U<n>' implies that the numeric value '<n>' is\n> mandatory. However, the command line parser has historically accepted\n> '-U' without a number.\n>\n> Strictly requiring a number for '-U' would break existing tests\n> (e.g., in 't4013') and likely disrupt user scripts relying on this\n> undocumented behavior.\n>\n> Since we are retaining this fallback behavior for backward compatibility,\n> update the documentation to explicitly state that '<n>' can be omitted\n> for the short option '-U'.\n>\n> Signed-off-by: Tian Yuchen <cat@malon.dev>\n> ---\n>  Documentation/diff-context-options.adoc | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n>\n> diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc\n> index e161260358..655496ec3a 100644\n> --- a/Documentation/diff-context-options.adoc\n> +++ b/Documentation/diff-context-options.adoc\n> @@ -1,4 +1,4 @@\n> -`-U<n>`::\n> +`-U[<n>]`::\n>  `--unified=<n>`::\n>         Generate diffs with _<n>_ lines of context. Defaults to `diff.context`\n>         or 3 if the config option is unset.\n> --\n> 2.43.0\n\nI was curious about the way we indicate this kind of optionality for\nsingle-letter options, so:\n\n    git grep -e '-[[:alnum:]]\\[' Documentation\n\nwhich finds many hits of this pattern. Cool. Adding -A1, we see that\nit is also common to document the long-form like\n\n    --unified[=<n>]\n\nwhich you may want to add to this patch. (I haven't really considered\nthe rest of it very well, although it does seem worth updating the\nsyntax to match what some of our tests exercise.)\n\nWhich makes me notice: 3 is the default if the config option is unset\n_or_ if <n> is not provided. Is there a better wording to indicate\nthat? Maybe the simplest tweak is to clarify that <n> is the thing\nwhich defaults to… (since a first read might leave the reader\nwondering \"what defaults to diff.context or 3? ah, it's probably n…\").\nBut a glance at other docs makes this pattern seem common while some\ndo say \"if <n> is specified…\", so idk.\n\nBTW I noticed these docs are duplicated between\nDocumentation/diff-{,context-}options.adoc\n\n-- \nD. Ben Knoble\n"},{"id":"538328","messageId":"xmqqwlzk1wd8.fsf@gitster.g","threadId":"65158","inReplyTo":"20260309172719.125419-1-cat@malon.dev","subject":"Re: [PATCH v1] diff: document -U without <n> as using default context","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-09T22:17:07Z","receivedAt":"2026-03-09T22:17:10Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tian Yuchen <cat@malon.dev> writes:\n\n> The documentation for '-U<n>' implies that the numeric value '<n>' is\n> mandatory. However, the command line parser has historically accepted\n> '-U' without a number.\n>\n> Strictly requiring a number for '-U' would break existing tests\n> (e.g., in 't4013') and likely disrupt user scripts relying on this\n> undocumented behavior.\n>\n> Since we are retaining this fallback behavior for backward compatibility,\n> update the documentation to explicitly state that '<n>' can be omitted\n> for the short option '-U'.\n>\n> Signed-off-by: Tian Yuchen <cat@malon.dev>\n> ---\n>  Documentation/diff-context-options.adoc | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n\nI am moderately nagative.\n\nIt is not like we are _encouraging_ users to omit <n> from -U<n>,\nbut it is not errored out only due to a bug.  Who would the new text\nhelp?  Users would wonder why <n> is not optional in --unified=<n>,\nthe other way to spell the same thing.\n\nIf we want to be explicit, we should probably do this instead:\n\n    `-U<n>`::\n    `--unified=<n>`::\n            Generate diffs with _<n>_ lines of context. Defaults to `diff.context`\n            or 3 if the config option is unset (`-U` without '<n>' is accepted\n            as a silent synonym for `-p` due to a historical accident).\n\nwhich would tell readers what happens when '<n>' is omitted and why\nwe allow such an inconsistency.\n\n"},{"id":"538356","messageId":"71287f25-eb60-4a45-b4ac-9368053c9183@malon.dev","threadId":"65158","inReplyTo":"xmqqwlzk1wd8.fsf@gitster.g","subject":"Re: [PATCH v1] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-10T04:51:23Z","receivedAt":"2026-03-10T04:51:31Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"Hi Junio,\n\n> I am moderately nagative.\n> \n> It is not like we are _encouraging_ users to omit <n> from -U<n>,\n> but it is not errored out only due to a bug.  Who would the new text\n> help?  Users would wonder why <n> is not optional in --unified=<n>,\n> the other way to spell the same thing.\n\nIndeed.\n\nWhat I was actually thinking earlier was: for bugs like this, which most \nlikely come from misoperations, typos, or inconsistencies from *ancient* \nstandards, should we acknowledge them as\n\n“yes it is a bug/historical issue”\n\nor\n\n“*special behavior* we defined”?\n\nI'm not as familiar with the Git codebase as you are, so I couldn't make \na definitive call. I chose the second approach, but I now agree the \nfirst makes more sense. In other words, users shouldn't be *encouraged* \nto engage in such behavior, right?\n\n> If we want to be explicit, we should probably do this instead:\n> \n>      `-U<n>`::\n>      `--unified=<n>`::\n>              Generate diffs with _<n>_ lines of context. Defaults to `diff.context`\n>              or 3 if the config option is unset (`-U` without '<n>' is accepted\n>              as a silent synonym for `-p` due to a historical accident).\n> \n> which would tell readers what happens when '<n>' is omitted and why\n> we allow such an inconsistency.\n\nThat makes sense. I'll make the changes accordingly.\n\nRegards,\n\nYuchen\n"},{"id":"538358","messageId":"fcc68ecb-09b1-4063-bcdf-5052eb42dfcf@malon.dev","threadId":"65158","inReplyTo":"CALnO6CAJfton4KwywVeRFbynWH9zu4nY4c6uXOnEdddKtZpeqA@mail.gmail.com","subject":"Re: [PATCH v1] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-10T04:55:02Z","receivedAt":"2026-03-10T04:55:09Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"Hi Ben,\n\nOn 3/10/26 06:00, D. Ben Knoble wrote:\n\n> Which makes me notice: 3 is the default if the config option is unset\n> _or_ if <n> is not provided. Is there a better wording to indicate\n> that? Maybe the simplest tweak is to clarify that <n> is the thing\n> which defaults to… (since a first read might leave the reader\n> wondering \"what defaults to diff.context or 3? ah, it's probably n…\").\n> But a glance at other docs makes this pattern seem common while some\n> do say \"if <n> is specified…\", so idk.\n\nIndeed, the current wording isn't clear enough. I'll make corrections \nwherever it's needed. I think Junio provides a good template that's \ngreat with just a few tweaks ;)\n\nThanks for the review!\n\nYuchen\n\n\n\n"},{"id":"538360","messageId":"20260310053032.129327-1-cat@malon.dev","threadId":"65158","inReplyTo":"20260309172719.125419-1-cat@malon.dev","subject":"[PATCH v2] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-10T05:30:32Z","receivedAt":"2026-03-10T05:31:21Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"The documentation for '-U<n>' implies that the numeric value '<n>' is\nmandatory. However, the command line parser has historically accepted\n'-U' without a number.\n\nStrictly requiring a number for '-U' would break existing tests\n(e.g., in 't4013') and likely disrupt user scripts relying on this\nundocumented behavior.\n\nSince we are retaining this fallback behavior for backward compatibility,\nupdate the documentation to explicitly state that '<n>' can be omitted\nfor the short option '-U'.\n\nSigned-off-by: Tian Yuchen <cat@malon.dev>\n---\n Documentation/diff-context-options.adoc | 6 ++++--\n Documentation/diff-options.adoc         | 6 ++++--\n 2 files changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc\nindex e161260358..42d29a0c00 100644\n--- a/Documentation/diff-context-options.adoc\n+++ b/Documentation/diff-context-options.adoc\n@@ -1,7 +1,9 @@\n `-U<n>`::\n `--unified=<n>`::\n-\tGenerate diffs with _<n>_ lines of context. Defaults to `diff.context`\n-\tor 3 if the config option is unset.\n+\tGenerate diffs with _<n>_ lines of context. The number of context\n+\tlines defaults to `diff.context` or 3 if the config option is unset.\n+\t(`-U` without `<n>` is accepted as a silent synonym for `-p` due\n+\tto a historical accident).\n \n `--inter-hunk-context=<n>`::\n \tShow the context between diff hunks, up to the specified _<number>_\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex 9cdad6f72a..40502639a2 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -127,8 +127,10 @@ endif::git-log[]\n \n `-U<n>`::\n `--unified=<n>`::\n-\tGenerate diffs with _<n>_ lines of context instead of\n-\tthe usual three.\n+\tGenerate diffs with _<n>_ lines of context. The number of context\n+\tlines defaults to `diff.context` or 3 if the config option is unset.\n+\t(`-U` without `<n>` is accepted as a silent synonym for `-p` due\n+\tto a historical accident).\t\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n-- \n2.43.0\n\n"},{"id":"538372","messageId":"aa_hTifKYZ5KYREv@ugly.lan","threadId":"65158","inReplyTo":"20260310053032.129327-1-cat@malon.dev","subject":"Re: [PATCH v2] diff: document -U without <n> as using default context","fromName":"Oswald Buddenhagen","fromEmail":"oswald.buddenhagen@gmx.de","sentAt":"2026-03-10T09:15:58Z","receivedAt":"2026-03-10T09:16:03Z","isPatch":true,"sender":{"key":"oswald.buddenhagen@gmx.de","avatar":"https://avatars.githubusercontent.com/u/812380?v=4"},"body":"On Tue, Mar 10, 2026 at 01:30:32PM +0800, Tian Yuchen wrote:\n>The documentation for '-U<n>' implies that the numeric value '<n>' is\n>mandatory. However, the command line parser has historically accepted\n>'-U' without a number.\n>\n>Strictly requiring a number for '-U' would break existing tests\n>(e.g., in 't4013') and likely disrupt user scripts relying on this\n>undocumented behavior.\n\n\n>Since we are retaining this fallback behavior for backward compatibility,\n>update the documentation to explicitly state that '<n>' can be omitted\n>for the short option '-U'.\n>\ni'd replace that with:\n\nHence we retain this fallback behavior for backward compatibility, but \ndocument it as such.\n\n>+\t(`-U` without `<n>` is accepted as a silent synonym for `-p` due\n>+\tto a historical accident).\n> \n\"silently accepted as a synonym\" would be much more natural.\n"},{"id":"538374","messageId":"736d3c7a-49cf-4ed5-9686-5a653caa20a4@malon.dev","threadId":"65158","inReplyTo":"aa_hTifKYZ5KYREv@ugly.lan","subject":"Re: [PATCH v2] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-10T09:43:48Z","receivedAt":"2026-03-10T09:44:04Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"On 3/10/26 17:15, Oswald Buddenhagen wrote:\n\n> i'd replace that with:\n> \n> Hence we retain this fallback behavior for backward compatibility, but \n> document it as such.\n> \n>> +    (`-U` without `<n>` is accepted as a silent synonym for `-p` due\n>> +    to a historical accident).\n>>\n> \"silently accepted as a synonym\" would be much more natural.\n\nThank you for pointing out. This change does make the message read more \nsmoothly.\n\nWill send v3 shortly.\n\nYuchen\n"},{"id":"538375","messageId":"20260310095017.131957-1-cat@malon.dev","threadId":"65158","inReplyTo":"20260309172719.125419-1-cat@malon.dev","subject":"[PATCH v3] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-10T09:50:17Z","receivedAt":"2026-03-10T09:50:41Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"The documentation for '-U<n>' implies that the numeric value '<n>' is\nmandatory. However, the command line parser has historically accepted\n'-U' without a number.\n\nStrictly requiring a number for '-U' would break existing tests\n(e.g., in 't4013') and likely disrupt user scripts relying on this\nundocumented behavior.\n\nHence we retain this fallback behavior for backward compatibility, but\ndocument it as such.\n\nSigned-off-by: Tian Yuchen <cat@malon.dev>\n---\n Documentation/diff-context-options.adoc | 6 ++++--\n Documentation/diff-options.adoc         | 6 ++++--\n 2 files changed, 8 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc\nindex e161260358..306abfd9ab 100644\n--- a/Documentation/diff-context-options.adoc\n+++ b/Documentation/diff-context-options.adoc\n@@ -1,7 +1,9 @@\n `-U<n>`::\n `--unified=<n>`::\n-\tGenerate diffs with _<n>_ lines of context. Defaults to `diff.context`\n-\tor 3 if the config option is unset.\n+\tGenerate diffs with _<n>_ lines of context. The number of context\n+\tlines defaults to `diff.context` or 3 if the config option is unset.\n+\t(`-U` without `<n>` is silently accepted as a synonym for `-p` due\n+\tto a historical accident).\n \n `--inter-hunk-context=<n>`::\n \tShow the context between diff hunks, up to the specified _<number>_\ndiff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc\nindex 9cdad6f72a..e1f20bedf6 100644\n--- a/Documentation/diff-options.adoc\n+++ b/Documentation/diff-options.adoc\n@@ -127,8 +127,10 @@ endif::git-log[]\n \n `-U<n>`::\n `--unified=<n>`::\n-\tGenerate diffs with _<n>_ lines of context instead of\n-\tthe usual three.\n+\tGenerate diffs with _<n>_ lines of context. The number of context\n+\tlines defaults to `diff.context` or 3 if the config option is unset.\n+\t(`-U` without `<n>` is silently accepted as a synonym for `-p` due\n+\tto a historical accident).\t\n ifndef::git-format-patch[]\n \tImplies `--patch`.\n endif::git-format-patch[]\n-- \n2.43.0\n\n"},{"id":"538418","messageId":"xmqqfr67yggf.fsf@gitster.g","threadId":"65158","inReplyTo":"aa_hTifKYZ5KYREv@ugly.lan","subject":"Re: [PATCH v2] diff: document -U without <n> as using default context","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2026-03-10T13:14:24Z","receivedAt":"2026-03-10T13:14:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Oswald Buddenhagen <oswald.buddenhagen@gmx.de> writes:\n\n>>Since we are retaining this fallback behavior for backward compatibility,\n>>update the documentation to explicitly state that '<n>' can be omitted\n>>for the short option '-U'.\n>>\n> i'd replace that with:\n>\n> Hence we retain this fallback behavior for backward compatibility, but \n> document it as such.\n>\n>>+\t(`-U` without `<n>` is accepted as a silent synonym for `-p` due\n>>+\tto a historical accident).\n>> \n> \"silently accepted as a synonym\" would be much more natural.\n\nAn excellent suggestion.  Thanks.\n"},{"id":"538481","messageId":"5973423.DvuYhMxLoT@piment-oiseau","threadId":"65158","inReplyTo":"20260309172719.125419-1-cat@malon.dev","subject":"Re: [PATCH v1] diff: document -U without <n> as using default context","fromName":"Jean-Noël AVILA","fromEmail":"avila.jn@gmail.com","sentAt":"2026-03-10T17:31:14Z","receivedAt":"2026-03-10T17:39:25Z","isPatch":true,"sender":{"key":"jn.avila@free.fr","avatar":"https://avatars.githubusercontent.com/u/156172?v=4"},"body":"On Monday, 9 March 2026 18:27:19 CET Tian Yuchen wrote:\n> The documentation for '-U<n>' implies that the numeric value '<n>' is\n> mandatory. However, the command line parser has historically accepted\n> '-U' without a number.\n> \n> Strictly requiring a number for '-U' would break existing tests\n> (e.g., in 't4013') and likely disrupt user scripts relying on this\n> undocumented behavior.\n> \n> Since we are retaining this fallback behavior for backward compatibility,\n> update the documentation to explicitly state that '<n>' can be omitted\n> for the short option '-U'.\n\nIn this case, isn't the long option also changed to optional number, such as:\n\n`--unified[=<n>]`\n\n?\n\n> \n> Signed-off-by: Tian Yuchen <cat@malon.dev>\n> ---\n>  Documentation/diff-context-options.adoc | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/diff-context-options.adoc\n> b/Documentation/diff-context-options.adoc index e161260358..655496ec3a \n100644\n> --- a/Documentation/diff-context-options.adoc\n> +++ b/Documentation/diff-context-options.adoc\n> @@ -1,4 +1,4 @@\n> -`-U<n>`::\n> +`-U[<n>]`::\n>  `--unified=<n>`::\n>  \tGenerate diffs with _<n>_ lines of context. Defaults to \n`diff.context`\n>  \tor 3 if the config option is unset.\n\n\n\n\n"},{"id":"538552","messageId":"9fc9fb8b-5f91-4670-a674-76774c31d228@malon.dev","threadId":"65158","inReplyTo":"5973423.DvuYhMxLoT@piment-oiseau","subject":"Re: [PATCH v1] diff: document -U without <n> as using default context","fromName":"Tian Yuchen","fromEmail":"cat@malon.dev","sentAt":"2026-03-11T04:33:31Z","receivedAt":"2026-03-11T04:33:38Z","isPatch":true,"sender":{"key":"cat@malon.dev","avatar":"https://avatars.githubusercontent.com/u/232002048?v=4"},"body":"On 3/11/26 01:31, Jean-Noël AVILA wrote:\n\n> In this case, isn't the long option also changed to optional number, such as:\n> \n> `--unified[=<n>]`\n> \n> ?\n\nIndeed. Your statement aligns with what Junio said earlier.\n\n>> The documentation for '-U<n>' implies that the numeric value '<n>' is\n>> mandatory. However, the command line parser has historically accepted\n>> '-U' without a number.\n>>\n>> Strictly requiring a number for '-U' would break existing tests\n>> (e.g., in 't4013') and likely disrupt user scripts relying on this\n>> undocumented behavior.\n>>\n>> Since we are retaining this fallback behavior for backward compatibility,\n>> update the documentation to explicitly state that '<n>' can be omitted\n>> for the short option '-U'.\n>>\n>> Signed-off-by: Tian Yuchen <cat@malon.dev>\n>> ---\n>>  Documentation/diff-context-options.adoc | 2 +-\n>>  1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> I am moderately nagative.\n> \n> It is not like we are _encouraging_ users to omit <n> from -U<n>,\n> but it is not errored out only due to a bug.  Who would the new text\n> help?  Users would wonder why <n> is not optional in --unified=<n>,\n> the other way to spell the same thing.\n> \n> If we want to be explicit, we should probably do this instead:\n> \n>     `-U<n>`::\n>     `--unified=<n>`::\n>             Generate diffs with _<n>_ lines of context. Defaults to `diff.context`\n>             or 3 if the config option is unset (`-U` without '<n>' is accepted\n>             as a silent synonym for `-p` due to a historical accident).\n> \n> which would tell readers what happens when '<n>' is omitted and why\n> we allow such an inconsistency.\n\nI have already fixed this in the v3 patch.\n\nThank you,\n\nYuchen\n\n"}]}