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

From: Emily Shaffer <[email-masked]>
Date: Mon, 29 Mar 2021 17:10:54 -0700

On Fri, Mar 12, 2021 at 10:29:52AM +0100, Ævar Arnfjörð Bjarmason wrote:
> 
> 
> 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.:

Yeah, this seems reasonable.

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

Maybe so. What I really would like would be if `git help githooks` //
`man githooks` opened `git-hook` manpage, but I had trouble getting it to do
that and still publish to the `githooks` manpage (because the command
doc format doesn't match the guide format). (Or, really, if `git help
githooks` didn't exist so we didn't need to split the docs up. But that
ship has sailed.)

Regardless, I won't complain that much about using a link instead. I'll
make this change for v9.

 - Emily