Re: git-subtree docs missing

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Nov 18, 2022, 19:56 UTC
Message-ID: <221118.86edu0f2ux.gmgdl@evledraar.gmail.com>
In-Reply-To: <Y3fKTpufVB5oTfkD@nand.local>

On Fri, Nov 18 2022, Taylor Blau wrote:

Show 10 quoted lines

> 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/