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

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Fri, 12 Mar 2021 10:29:52 +0100

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.