diff: avoid misleading statement about -l option
PATCH 1/1 diff: avoid misleading statement about -l option
From: Elijah Newren <[email protected]>
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.
---
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.c +1 -1
@@ -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
Signature · 1 line
gitgitgadget
Quoted 10 lines · Elijah Newren via GitGitGadget
From: Elijah Newren <[email protected]>
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.
Quoted 2 lines
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?
Quoted 4 lines · Junio C Hamano
Quoted 1 line · Elijah Newren via GitGitGadget
From: Elijah Newren <[email protected]>
Oops, I had author != committer (and author != signoff). I'll fix that up and send in a .mailmap entry too.
Quoted 8 lines
Quoted 8 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.
Quoted 6 lines
Quoted 2 lines
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 1/1 diff: avoid misleading statement about -l option
In reply to Elijah Newren via GitGitGadgetFrom: Elijah Newren <[email protected]>
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.
---
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 <[email protected]>
+Author: Elijah Newren <[email protected]>
## 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.c +1 -1
@@ -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
Signature · 1 line
gitgitgadget
diff.c struct option *add_diff_options(const struct option *opts, · line 6189
Quoted 10 lines · Elijah Newren via GitGitGadget
diff.c +1
-1@@ -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.
Quoted 5 lines
diff.c +0
-0OPT_GROUP (N_ ("Diff algorithm options" )), OPT_CALLBACK_F(0, "minimal", options, NULL,base-commit:
2c78326f810173a4f3aefd8021f1e07575412481