diff_unique_abbrev(): document its assumption and limitation
This function is used to add "..." to displayed object names in "diff --raw --abbrev[=<n>]" output. It bases its behaviour on an untold assumption that the abbreviation length requested by the caller is "reasonble", i.e. most of the objects will abbreviate within the requested length and the resulting length would never exceed it by more than a few hexdigits (otherwise the resulting columns would not align). Explain that in a comment. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Sep 30, 2016 at 10:42 UTC
d709f1fb9d3bfa148dd8b461e633138fdf5957e6
1 file changed
+22
-1
diff.c
+22
-1
@@ -4089,7 +4089,8 @@ void diff_free_filepair(struct diff_filepair *p)
4089
free(p);
4090
}
4091
4092
-/* This is different from find_unique_abbrev() in that
4092
+/*
4093
+ * This is different from find_unique_abbrev() in that
4094
* it stuffs the result with dots for alignment.
4095
*/
4096
const char *diff_unique_abbrev(const unsigned char *sha1, int len)
@@ -4101,6 +4102,26 @@ const char *diff_unique_abbrev(const unsigned char *sha1, int len)
4102
4103
abbrev = find_unique_abbrev(sha1, len);
4104
abblen = strlen(abbrev);
4105
+
4106
+ /*
4107
+ * In well-behaved cases, where the abbbreviated result is the
4108
+ * same as the requested length, append three dots after the
4109
+ * abbreviation (hence the whole logic is limited to the case
4110
+ * where abblen < 37); when the actual abbreviated result is a
4111
+ * bit longer than the requested length, we reduce the number
4112
+ * of dots so that they match the well-behaved ones. However,
4113
+ * if the actual abbreviation is longer than the requested
4114
+ * length by more than three, we give up on aligning, and add
4115
+ * three dots anyway, to indicate that the output is not the
4116
+ * full object name. Yes, this may be suboptimal, but this
4117
+ * appears only in "diff --raw --abbrev" output and it is not
4118
+ * worth the effort to change it now. Note that this would
4119
+ * likely to work fine when the automatic sizing of default
4120
+ * abbreviation length is used--we would be fed -1 in "len" in
4121
+ * that case, and will end up always appending three-dots, but
4122
+ * the automatic sizing is supposed to give abblen that ensures
4123
+ * uniqueness across all objects (statistically speaking).
4124
+ */
4125
if (abblen < 37) {
4126
static char hex[41];
4127
if (len < abblen && abblen <= len + 2)