From: Jeff Hostetler Date: Thu, 08 Apr 2021 20:20:56 GMT Subject: Re: [PATCH v8 37/37] docs: unify githooks and git-hook manpages Message-ID: <7b651fbf-7f54-21b3-3775-d18c20f85a1a@jeffhostetler.com> In-Reply-To: On 4/6/21 10:36 PM, Junio C Hamano wrote: > Emily Shaffer 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 >> --- >> 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 expect the fsmonitor stuff to take a while. It is rather large and complicated. My changes in the Documentation are rather minor. And I wouldn't want to be the sole reason to hold up Emily's changes. If it would be helpful, you can add a "revert" commit on top of my branch for my documentation commit -or- just drop it completely from my series. Then I can re-adjust/rebase my doc changes before I send a V2. Jeff