Re: [PATCH v8 37/37] docs: unify githooks and git-hook manpages

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Mar 12, 2021, 09:29 UTC
Message-ID: <87sg50g1nz.fsf@evledraar.gmail.com>
In-Reply-To: <20210311021037.3001235-38-emilyshaffer@google.com>

On Thu, Mar 11 2021, Emily Shaffer wrote:

> By showing the list of all hooks in 'git help hook' for users to refer
> to, 'git help hook' becomes a one-stop shop for hook authorship. Since
> some may still have muscle memory for 'git help githooks', though,
> reference the 'git hook' commands and otherwise don't remove content.

I think this should at least have something like what my b6a8d09f6d8 (gc
docs: include the "gc.*" section from "config" in "gc", 2019-04-07) has
on top, i.e.:
    
    diff --git a/Documentation/git-hook.txt b/Documentation/git-hook.txt
    index 4ad31ac360a..5c9af30b43e 100644
    --- a/Documentation/git-hook.txt
    +++ b/Documentation/git-hook.txt
    @@ -150,10 +150,18 @@ message body and cannot be parallelized.
     
     CONFIGURATION
     -------------
    +
    +The below documentation is the same as what's found in
    +linkgit:git-config[1]:
    +
     include::config/hook.txt[]
     
     HOOKS
     -----
    +
    +The below documentation is the same as what's found in
    +linkgit:githooks[5]:
    +
     include::native-hooks.txt[]
     
     GIT

But I also don't think we should demote githooks(5) as the canonical doc page for the hooks themselves.

If you run this in your terminal:

    man 5 git<TAB>

You'll get:

    gitattributes         gitignore             gitmailmap            gitrepository-layout  
    githooks              git-lfs-config        gitmodules            gitweb.conf

(Well, maybe not the lfs-part, but whatever...).

We should move more in the direction of splitting up our "file format" docs from implementation, like the git-hook runner.

I'm somewhat negative on including it at all in git-hook(1). For the config section it makes sense, and it's consistent with established doc convention.

But including githooks(5) is around 2/3 of the resulting manpage, I think just a link is better.