diff: document -U without <n> as using default context

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.

Hence we retain this fallback behavior for backward compatibility, but
document it as such.

Signed-off-by: Tian Yuchen <cat@malon.dev>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/diff-context-options.adoc b/Documentation/diff-context-options.adoc
index e161260358fff58990736f9d3b20077572cfc282..b9ace2aa4b309298b284ff9f988592e9727c62f5 100644 (file)
--- 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 configuration variable
+       is unset. (`-U` without `<n>` is silently accepted as a 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 9cdad6f72a0c7d9186166c3d8789c531732b74ea..867bef631280e3128a6175b69273b9cfe752dfd2 100644 (file)
--- 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 configuration variable
+       is unset. (`-U` without `<n>` is silently accepted as a synonym for
+       `-p` due to a historical accident).
 ifndef::git-format-patch[]
        Implies `--patch`.
 endif::git-format-patch[]