Re: git-subtree docs missing

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Fri, Nov 18 2022, Taylor Blau wrote:

> On Fri, Nov 18, 2022 at 06:03:36PM +0000, David Cowden wrote:
>> However I'm now aware that `git-subtree` is part of contrib and not
>> officially part of git so my expectations for finding documentation
>> there may be wrong.
>
> Right. We don't have any standardized documentation in the contrib tree,
> so it isn't built for git-scm.com.
>
> The documentation we do have for 'git subtree' is at
> contrib/subtree/git-subtree.txt.

I think changing this would still be worthwhile. We've since made
"scalar" non-contrib, but when the discussion about how to do that was
ongoing I suggested creating a section in "git(1)" for "Optional contrib
commands"[1].

The eventual idea being that we'd always build e.g. the git-subtree
docs, but would not install the command by default.

I can dig it up if there's interest. I really think it's much better
than what we're currently doing.

I.e. we don't want "git-subtree.sh" to be "blessed" (for reasons outside
of the scope of this discussion), but I don't see why that would extend
to its docs not being accessible, and us not testing it by default as
part of "make test" etc.

My first encounter with "git-subtree" was of finding it on one system,
having a manual page for it, and then being preplexed that another
system didn't have it. I then found out through other means that it was
"contrib", and only optionally installed.

We'd still have it be optionally installed, but we're not doing anyone
any favors in not linking to it as part of our docs, and having some
blurb describing that it's shipped with git sometimes, but not part of
the main command set.

1. https://lore.kernel.org/git/cover-v2-0.1-00000000000-20220623T100554Z-avarab@gmail.com/