Re: [PATCH] git-sh-setup: Restore sourcability from outside scripts

From: Philip Oakley <philipoakley@iee.org>
Date: Oct 30, 2016, 20:09 UTC
Message-ID: <223121D101D844DEBF086AC40A5AF4CB@PhilipOakley>
In-Reply-To: <alpine.DEB.2.10.1610301503280.60842@buzzword-bingo.mit.edu>

From: "Anders Kaseorg" <andersk@mit.edu>

Show 16 quoted lines

> On Sun, 30 Oct 2016, Ævar Arnfjörð Bjarmason wrote:
>> This seems like a reasonable fix for this issue. However as far as I
>> can tell git-sh-setup was never meant to be used by outside scripts
>> that didn't ship as part of git itself.
>>
>> If that's the case any change in the API which AFAICT is now
>> considered internal might break them, so should some part of that be
>> made public & documented as such?
>
> It is documented (Documentation/git-sh-setup.txt), and this is not the
> internal Documentation/technical section of the documentation, so my
> default assumption would be that everything shown there is intended as
> public.  I only bring this up as a question because it was apparently
> allowed to break.  If I’m wrong and it isn’t public, other patches are
> needed (to the documentation and to its users in contrib).
>

But the Documenation does say ::

- This is not a command the end user would want to run. Ever.

- This documentation is meant for people who are studying the Porcelain-ish 
scripts and/or are writing new ones.
--

So there is a cautionary word or two there...

The question would then become: what (if anything) was missing in the documentation?... maybe the inclusion of Ævar's "[Not] to be used by outside scripts that didn't ship as part of git itself."? Or a comment that it may change in newer versions. Though the code fix may still be reasonable..

Philip