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

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Oct 30, 2016, 22:11 UTC
Message-ID: <CACBZZX6ArQdG202n-SouwDhoTE1LF=69mKjWQv8HPKJ+K_0fJQ@mail.gmail.com>
In-Reply-To: <20161030211227.4gqovv7mt7mtnpy7@sigill.intra.peff.net>

,On Sun, Oct 30, 2016 at 10:12 PM, Jeff King <peff@peff.net> wrote:

Show 30 quoted lines

> On Sun, Oct 30, 2016 at 08:09:21PM -0000, Philip Oakley wrote:
>
>> > 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.
>> --
>
> Historically speaking, porcelain-ish scripts were carried both in and
> out of git.git. These days what we consider porcelain is usually carried
> in-tree, but I don't think it's unreasonable for people building their
> own scripts to want to make use of git-sh-setup. And we've generally
> tried to retain backwards compatibility in the functions it provides,
> even to out-of-tree scripts.
>
> So I think it is worth applying the fix at the start of this thread to
> keep that working.
>
> As for a documentation change for "do not use this for out-of-tree
> scripts", I am mildly negative, as I don't think that matches historical
> practice.

I don't see why we shouldn't have some stable shellscript function API if that's needed either.

I just wanted to point out that currently git-sh-setup isn't documented as such. So at least a follow-up patch to the documentation seems in order.

This did break in v2.10.0, and it's taken a couple of months to notice this, so clearly it's not very widely used, which says something about the cost-benefit of maintaining this for external users.

It's probably worthwhile to split off git-sh-setup into git-sh-setup & git-sh-setup-internal along with a documentation fix. A lot of what it's doing (e.g. git_broken_path_fix(), and adding a die() function) is probably only needed internally by git itself. The git-sh-setup-internal should be the thing sourcing "git-sh-i18n", I don't see how anyone out-of-tree could make use of that. Surely nobody needs to re-emit the exact message we shipped with our *.po files.