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
