Re: [PATCH v3 1/2] name-rev: deprecate --stdin in favor of --annotate-text

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 4, 2022, 19:00 UTC
Message-ID: <xmqqo84re36w.fsf@gitster.g>
In-Reply-To: <77e18a78-ddfe-0337-deaf-bb9dfb63a495@iee.email>

Philip Oakley <philipoakley@iee.email> writes:

Show 12 quoted lines

>>  --stdin::
>> +	This option is deprecated in favor of 'git name-rev --annotate-stdin'.
>> +	They are functionally equivalent.
>> +
>> +--annotate-stdin::
>>  	Transform stdin by substituting all the 40-character SHA-1
>>  	hexes (say $hex) with "$hex ($rev_name)".  When used with
>>  	--name-only, substitute with "$rev_name", omitting $hex
>> -	altogether.  Intended for the scripter's use.
>> +	altogether.
>
> Is there a preferred order for the old/new variant documentation?

If the surrounding list has a natural order of its own, e.g. the list is sorted alphabetically to help people locate an item by name, it is OK to have old and new in that order and older one may appear before the newer one.

But otherwise it may make sense to show the newer one first with the mention of the older one as if it were a side note, especially when they can appear next to each other like the one we are looking at, I would think.

I do not think we have written preference. It probably would help to have a short paragraph in the coding guidelines document.

Thanks.