[PATCH] diff: avoid misleading statement about -l option

[PATCH] diff: avoid misleading statement about -l option

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@github.com>

In commit 6623a528e00b (doc: clarify documentation for rename/copy
limits, 2021-07-15), the wording around rename limit options and config
variables were updated to point out that only the quadratic portion of
rename detection (or "exhaustive portion of rename/copy detection" as
used in that commit) was limited by these options, because exact rename
detection and basename-guided rename detection (which both run in time
linear in the number of files) still run before this limit is checked.

However, the short help message wasn't updated at the time; update it
too.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
    diff: avoid misleading statement about -l option

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2035%2Fnewren%2Fdiff-l-option-doc-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2035/newren/diff-l-option-doc-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2035

 diff.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/diff.c b/diff.c
index a68ddd2168..0aa910a2c0 100644
--- a/diff.c
+++ b/diff.c
@@ -5871,7 +5871,7 @@ struct option *add_diff_options(const struct option *opts,
 			       N_("continue listing the history of a file beyond renames"),
 			       PARSE_OPT_NOARG, diff_opt_follow),
 		OPT_INTEGER('l', NULL, &options->rename_limit,
-			    N_("prevent rename/copy detection if the number of rename/copy targets exceeds given limit")),
+			    N_("prevent exhaustive portion of rename/copy detection if the number of rename/copy targets exceeds given limit")),
 
 		OPT_GROUP(N_("Diff algorithm options")),
 		OPT_CALLBACK_F(0, "minimal", options, NULL,

base-commit: 7264e61d87e58b9d0f5e6424c47c11e9657dfb75
-- 
gitgitgadget

Re: [PATCH] diff: avoid misleading statement about -l option

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Elijah Newren <newren@github.com>
>
> In commit 6623a528e00b (doc: clarify documentation for rename/copy
> limits, 2021-07-15), the wording around rename limit options and config
> variables were updated to point out that only the quadratic portion of
> rename detection (or "exhaustive portion of rename/copy detection" as
> used in that commit) was limited by these options, because exact rename
> detection and basename-guided rename detection (which both run in time
> linear in the number of files) still run before this limit is checked.
>
> However, the short help message wasn't updated at the time; update it
> too.

However this is an end-user facing message.  Can we make it more
easier to understnad by being less precise?  "limit to exact
rename/copy if ..." or something?

Re: [PATCH] diff: avoid misleading statement about -l option

[Elijah Newren]

On Wed, Aug 12, 2026 at 7:22 AM Junio C Hamano <gitster@pobox.com> wrote:
>
> "Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Elijah Newren <newren@github.com>

Oops, I had author != committer (and author != signoff).  I'll fix
that up and send in a .mailmap entry too.

> > In commit 6623a528e00b (doc: clarify documentation for rename/copy
> > limits, 2021-07-15), the wording around rename limit options and config
> > variables were updated to point out that only the quadratic portion of
> > rename detection (or "exhaustive portion of rename/copy detection" as
> > used in that commit) was limited by these options, because exact rename
> > detection and basename-guided rename detection (which both run in time
> > linear in the number of files) still run before this limit is checked.
> >
> > However, the short help message wasn't updated at the time; update it
> > too.
>
> However this is an end-user facing message.  Can we make it more
> easier to understnad by being less precise?  "limit to exact
> rename/copy if ..." or something?

Maybe if we replace "exact" with either "cheap" or "linear"?

   "limit to cheap rename/copy detection if the number of rename/copy
targets exceeds this value" ?

That would also tie in with the documentation for -l:

`-l<num>`::
    The `-M` and `-C` options involve some preliminary steps that
    can detect subsets of renames/copies cheaply, followed by an
    exhaustive fallback portion that compares all remaining
    unpaired destinations to all relevant sources.

Since there are two cheap preliminary steps -- "exact" and
"basename-guided" rename detection -- using "cheap" correctly covers
both.  Does that sound reasonable?

[PATCH v2] diff: avoid misleading statement about -l option

[Elijah Newren via GitGitGadget]

From: Elijah Newren <newren@gmail.com>

In commit 6623a528e00b (doc: clarify documentation for rename/copy
limits, 2021-07-15), the wording around rename limit options and config
variables were updated to point out that only the quadratic portion of
rename detection (or "exhaustive portion of rename/copy detection" as
used in that commit) was limited by these options, because exact rename
detection and basename-guided rename detection (which both run in time
linear in the number of files) still run before this limit is checked.

However, the short help message wasn't updated at the time; update it
too.

Signed-off-by: Elijah Newren <newren@gmail.com>
---
    diff: avoid misleading statement about -l option
    
    Changes since v1:
    
     * Fixed author to match signoff
     * Simplified the wording a bit, along the lines of Junio's suggestion

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2035%2Fnewren%2Fdiff-l-option-doc-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2035/newren/diff-l-option-doc-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/2035

Range-diff vs v1:

 1:  6253e1dc96 ! 1:  58729a71ce diff: avoid misleading statement about -l option
     @@
       ## Metadata ##
     -Author: Elijah Newren <newren@github.com>
     +Author: Elijah Newren <newren@gmail.com>
      
       ## Commit message ##
          diff: avoid misleading statement about -l option
     @@ diff.c: struct option *add_diff_options(const struct option *opts,
       			       PARSE_OPT_NOARG, diff_opt_follow),
       		OPT_INTEGER('l', NULL, &options->rename_limit,
      -			    N_("prevent rename/copy detection if the number of rename/copy targets exceeds given limit")),
     -+			    N_("prevent exhaustive portion of rename/copy detection if the number of rename/copy targets exceeds given limit")),
     ++			    N_("limit to cheap rename/copy detection if the number of rename/copy targets exceeds this value")),
       
       		OPT_GROUP(N_("Diff algorithm options")),
       		OPT_CALLBACK_F(0, "minimal", options, NULL,


 diff.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/diff.c b/diff.c
index 589c1969e4..c593066592 100644
--- a/diff.c
+++ b/diff.c
@@ -6186,7 +6186,7 @@ struct option *add_diff_options(const struct option *opts,
 			       N_("continue listing the history of a file beyond renames"),
 			       PARSE_OPT_NOARG, diff_opt_follow),
 		OPT_INTEGER('l', NULL, &options->rename_limit,
-			    N_("prevent rename/copy detection if the number of rename/copy targets exceeds given limit")),
+			    N_("limit to cheap rename/copy detection if the number of rename/copy targets exceeds this value")),
 
 		OPT_GROUP(N_("Diff algorithm options")),
 		OPT_CALLBACK_F(0, "minimal", options, NULL,

base-commit: 2c78326f810173a4f3aefd8021f1e07575412481
-- 
gitgitgadget

Re: [PATCH v2] diff: avoid misleading statement about -l option

[Junio C Hamano]

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:

> diff --git a/diff.c b/diff.c
> index 589c1969e4..c593066592 100644
> --- a/diff.c
> +++ b/diff.c
> @@ -6186,7 +6186,7 @@ struct option *add_diff_options(const struct option *opts,
>  			       N_("continue listing the history of a file beyond renames"),
>  			       PARSE_OPT_NOARG, diff_opt_follow),
>  		OPT_INTEGER('l', NULL, &options->rename_limit,
> -			    N_("prevent rename/copy detection if the number of rename/copy targets exceeds given limit")),
> +			    N_("limit to cheap rename/copy detection if the number of rename/copy targets exceeds this value")),

That is still a mouthful and it does not help that rename/copy
appears twice, but that trait is shared with the original, so let's
leave it outside the topic to improve it.  If somebody is inclined
to, he or she can do so later.

Will mark it for 'next'.  Thanks.

>  
>  		OPT_GROUP(N_("Diff algorithm options")),
>  		OPT_CALLBACK_F(0, "minimal", options, NULL,
>
> base-commit: 2c78326f810173a4f3aefd8021f1e07575412481