gitdiffcore doc: mention new preliminary step for rename detection
The last few patches have introduced a new preliminary step when rename detection is on but both break detection and copy detection are off. Document this new step. While we're at it, add a testcase that checks the new behavior as well. Signed-off-by: Elijah Newren <newren@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Elijah Newren committed
Feb 14, 2021 at 07:51 UTC
07c9a7fcb50e7af9d350edc82d5f906a6eb6bd62
1 file changed
+20
Documentation/gitdiffcore.txt
+20
@@ -168,6 +168,26 @@ a similarity score different from the default of 50% by giving a
168
number after the "-M" or "-C" option (e.g. "-M8" to tell it to use
169
8/10 = 80%).
170
171
+Note that when rename detection is on but both copy and break
172
+detection are off, rename detection adds a preliminary step that first
173
+checks if files are moved across directories while keeping their
174
+filename the same. If there is a file added to a directory whose
175
+contents is sufficiently similar to a file with the same name that got
176
+deleted from a different directory, it will mark them as renames and
177
+exclude them from the later quadratic step (the one that pairwise
178
+compares all unmatched files to find the "best" matches, determined by
179
+the highest content similarity). So, for example, if a deleted
180
+docs/ext.txt and an added docs/config/ext.txt are similar enough, they
181
+will be marked as a rename and prevent an added docs/ext.md that may
182
+be even more similar to the deleted docs/ext.txt from being considered
183
+as the rename destination in the later step. For this reason, the
184
+preliminary "match same filename" step uses a bit higher threshold to
185
+mark a file pair as a rename and stop considering other candidates for
186
+better matches. At most, one comparison is done per file in this
187
+preliminary pass; so if there are several remaining ext.txt files
188
+throughout the directory hierarchy after exact rename detection, this
189
+preliminary step will be skipped for those files.
190
+
191
Note. When the "-C" option is used with `--find-copies-harder`
192
option, 'git diff-{asterisk}' commands feed unmodified filepairs to
193
diffcore mechanism as well as modified ones. This lets the copy