,On Sun, Oct 30, 2016 at 10:12 PM, Jeff King <peff@xxxxxxxx> wrote: > 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.