Volume XXII, number 279Tuesday, October 6, 2026Latest message 33 minutes ago

The Git List

News and archive of git@vger.kernel.org, since April 2005

patchdiff: avoid misleading statement about -l option

5 messages between Aug 12, 2026 and Aug 14, 2026, from Elijah Newren via GitGitGadget, Junio C Hamano, Elijah Newren.

Plain Markdown or JSON for tools and agents. Diffs are folded; open one to read it.

Elijah Newren via GitGitGadgetAug 12, 2026, 06:42 UTC on lore
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(-)
Show changes to diff.c +1 −1
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
Junio C HamanoAug 12, 2026, 14:22 UTC in reply to Elijah Newren via GitGitGadget on lore

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

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 12 quoted lines
> 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?

Elijah NewrenAug 12, 2026, 15:42 UTC in reply to Junio C Hamano on lore

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

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.

Show 14 quoted lines
> > 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?

Elijah Newren via GitGitGadgetAug 14, 2026, 02:06 UTC in reply to Elijah Newren via GitGitGadget on lore

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

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(-)
Show changes to diff.c +1 −1
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
Junio C HamanoAug 14, 2026, 14:26 UTC in reply to Elijah Newren via GitGitGadget on lore

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

"Elijah Newren via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 10 quoted lines
> 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.
Show 5 quoted lines
>  
>  		OPT_GROUP(N_("Diff algorithm options")),
>  		OPT_CALLBACK_F(0, "minimal", options, NULL,
>
> base-commit: 2c78326f810173a4f3aefd8021f1e07575412481

Back to recent threads

[PATCH] diff: avoid misleading statement about -l option | The Git List