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

From: Junio C Hamano <[email-masked]>
Date: Tue, 06 Apr 2021 19:36:15 -0700

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.