Eric Sunshine <sunshine@xxxxxxxxxxxxxx> writes: > Unfortunately, I'm not going to be much help here since I don't grok > "creation factor" well enough to put an explanation into words, even > after having read the "algorithm" section multiple times[1]. The > situation is further confused (at least to me) by the "algorithm" > section in the `git range-diff` documentation stating that the "fudge > factor ... should be smaller than 100%", yet your position in this > discussion is that the creation factor can be greater than 100%. > > FOOTNOTES > > [1]: I likewise didn't understand it well enough when submitting[2] > which added --creation-factor to `git format-patch`, which is why I > punted at that time and simply referred the reader to the `git > range-diff` documentation. So it wasn't just me or other folks who were confused in the original discussion thread that lead to https://lore.kernel.org/git/xmqqa68nlfiz.fsf@gitster.g/ where I said ... The former helps the readers guess what a reasonable value they want to specify is (e.g. "I can afford to dedicate yMB"), and the latter is essential for the readers to decide how exactly they express what they chose (e.g. "I want to give yMB, but it is measured in bytes, so I'll write y * 10^20 here"). We need both. So _after_ they decide that 1.20 is the right number they want to give to --creation-factor, the knowledge that the number is expressed as percent does help them to write --creation-factor=120 correctly (not --creation-factor=1.20). But for readers to come up with the number 1.20, there needs a better explanation of what the number means in the first place. "Go read the algorithm section" is better than having nothing there, but we should be able to do better by having a simple-to-understand single paragraph description. i.e. out of the current documentation, it is hard for readers to extract information they need to decide what value they want to specify. The part of it that talks about <percent> may tell them to spell "120" when they want to specify 1.20, but that is not all that helpful when they do not know what criteria they want to use to choose between 0.60 and 1.20 in the first place X-<.
