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

From: Emily Shaffer <[email-masked]>
Date: Thu, 8 Apr 2021 16:46:12 -0700

On Tue, Apr 06, 2021 at 07:36:15PM -0700, Junio C Hamano wrote:
> 
> Emily Shaffer <[email-masked]> writes:
> 
> > 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.
> >
> > Signed-off-by: Emily Shaffer <[email-masked]>
> > ---
> >  Documentation/git-hook.txt     |  11 +
> >  Documentation/githooks.txt     | 716 +--------------------------------
> >  Documentation/native-hooks.txt | 708 ++++++++++++++++++++++++++++++++
> >  3 files changed, 724 insertions(+), 711 deletions(-)
> >  create mode 100644 Documentation/native-hooks.txt
> 
> While this would be a very good move when this were the only topic
> juggling the hook related documentation, in the real world, it
> creates rather nasty "ouch, the original hooks document was updated,
> and we need to carry these changes over to the new native-hooks
> file" conflicts with multiple commits on different topics.
> 
> $ git log --oneline --no-merges es/config-hooks..seen Documentation/githooks.txt
> 2d4e48b8ee fsmonitor--daemon: man page and documentation
> 23c781f173 githooks.txt: clarify documentation on reference-transaction hook
> 5f308a89d8 githooks.txt: replace mentions of SHA-1 specific properties
> 7efc378205 doc: fix some typos
> 
> $ git log --oneline --no-merges ^master es/config-hooks..seen Documentation/githooks.txt
> 2d4e48b8ee fsmonitor--daemon: man page and documentation
> 
> As three of the four changes are already in master, it probably is a
> good idea to rebase this topic (and redo this step) to update the
> native-hooks.txt
> 
> I am not sure offhand how ready fsmonitor--daemon stuff is, but if
> it takes longer to stabilize than this topic, it might make sense to
> hold off the changes to githooks.txt in that topic, until this topic
> stabilizes enough to hit at least 'next', preferrably 'master', and
> then base that topic (or at least the documentation part of it) on
> the final shape of the native-hooks.txt.
> 
> Or better ideas?
> 
> Thanks.

I got bitten by this same issue with native-hooks.txt while addressing
comments, too. Another commenter suggested to not inline those hook
definitions into "git help hook" - so I plan to drop that part of this
patch. If it makes it easier for you, I think you could revert this last
commit; if we decide later that we want to have "git help hook" share
the hook definitions after all, I think we should do that separately and
as a quick change not stuck behind 36 other complicated patches.

 - Emily