Re: [RFC PATCH 1/1] filter-options: Expand abbreviated numbers

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 7, 2019, 22:18 UTC
Message-ID: <xmqqpnt86rii.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <xmqqva306rsy.fsf@gitster-ct.c.googlers.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 25 quoted lines

> Josh Steadmon <steadmon@google.com> writes:
>
>>> > -	`rev-list` for possible "filter-spec" values.
>>> > +	`rev-list` for possible "filter-spec" values. Clients MUST
>>> > +	translate abbreviated numbers (e.g. "1k") into fully-expanded
>>> > +	numbers (e.g. "1024") on the client side, so that the server
>>> > +	does not need to implement unit parsing.
>>> 
>>> I suspect that it is too late now to retroactively say "MUST" here.
>>> The best we may be able to do is to say "The sender SHOULD send a
>>> plain integer without unit and the receiver SHOULD be prepared to
>>> scale an integer with unit".
>>> 
>>
>> In that case, do you think we should also specify that units should be
>> interpreted as powers-of-2 rather than powers-of-10?
>
> If we do not document the number scaling elsewhere, then we
> certainly should, but I somehow doubt it.
>
> Documentation/git-config.txt does list these explicitly where it
> talks about --type=int, but these human-readable scaled integers are
> also used in command line arguments as well, so we may want to find
> a central place that is clear to the readers that the description
> applies to all of them and move the description there.

Another thing. We may probably end up adding more scaling factors, but going forward we would not want to require any and all Git reimplementations to adopt them in lock-step, so perhaps

    `rev-list` for possible "filter-spec" values.  Senders SHOULD
    translate a scaled integer (e.g. "1k") into a full expanded form
    (e.g. "1024") so that an older receiver that does not know newly
    invented scaling units can still interoperate with it, but
    receivers SHOULD accept the following scalilng units: 'k', 'm'
    and 'g' for 1024, 1048576 and 1073741824 respectively.

or something like that.