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

From: Tian Yuchen <[email-masked]>
Date: Tue, 10 Mar 2026 13:30:32 +0800

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 <[email-masked]>
---
 Documentation/diff-context-options.adoc | 6 ++++--
 Documentation/diff-options.adoc         | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc
index e161260358..42d29a0c00 100644
--- a/Documentation/diff-context-options.adoc
+++ b/Documentation/diff-context-options.adoc
@@ -1,7 +1,9 @@
 `-U<n>`::
 `--unified=<n>`::
-	Generate diffs with _<n>_ lines of context. Defaults to `diff.context`
-	or 3 if the config option is unset.
+	Generate diffs with _<n>_ lines of context. The number of context
+	lines 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).
 
 `--inter-hunk-context=<n>`::
 	Show the context between diff hunks, up to the specified _<number>_
diff --git a/Documentation/diff-options.adoc b/Documentation/diff-options.adoc
index 9cdad6f72a..40502639a2 100644
--- a/Documentation/diff-options.adoc
+++ b/Documentation/diff-options.adoc
@@ -127,8 +127,10 @@ endif::git-log[]
 
 `-U<n>`::
 `--unified=<n>`::
-	Generate diffs with _<n>_ lines of context instead of
-	the usual three.
+	Generate diffs with _<n>_ lines of context. The number of context
+	lines 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).	
 ifndef::git-format-patch[]
 	Implies `--patch`.
 endif::git-format-patch[]
-- 
2.43.0