{"thread":{"id":"61773","subject":"[PATCH] doc: clarify post-receive hook behavior","startedAt":"2024-07-12T22:50:22Z","lastAt":"2024-07-15T18:44:35Z","messageCount":8,"participants":["Justin Tobler","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"498600","messageId":"20240712224748.56843-1-jltobler@gmail.com","threadId":"61773","inReplyTo":null,"subject":"[PATCH] doc: clarify post-receive hook behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-07-12T22:47:48Z","receivedAt":"2024-07-12T22:50:22Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"The `githooks` documentation mentions that the post-receive hook\nexecutes once after git-receive-pack(1) updates all references and that\nit also receives the same information as the pre-receive hook on\nstandard input. This is misleading though because the hook only\nexecutes once if at least one of the attempted reference updates is\nsuccessful. Also, while each line provided on standard input is in the\nsame format as the pre-receive hook, the information received only\nincludes the set of references that were successfully updated.\n\nUpdate the documentation to clarify these points and also provide a\nreference to the post-receive hook section of the `git-receive-pack`\ndocumentation which has additional information.\n\nSigned-off-by: Justin Tobler <jltobler@gmail.com>\n\n---\n\nGreetings all,\n\nI was recently looking into post-receive hooks and found some of its\ndocumentation[1] a bit misleading. With this patch, the `githooks`\ndocumentation is updated to better align with the hooks documentation\nfor `git-receive-pack`[2]. Thanks for taking a look!\n\n-Justin\n\n1: https://git-scm.com/docs/githooks#post-receive\n2: https://git-scm.com/docs/git-receive-pack#_post_receive_hook\n---\n Documentation/githooks.txt | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex 06e997131b..f9eb396a79 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -415,13 +415,13 @@ post-receive\n \n This hook is invoked by linkgit:git-receive-pack[1] when it reacts to\n `git push` and updates reference(s) in its repository.\n-It executes on the remote repository once after all the refs have\n-been updated.\n+It executes on the remote repository once if any of the attempted ref\n+updates are successful.\n \n-This hook executes once for the receive operation.  It takes no\n-arguments, but gets the same information as the\n-<<pre-receive,'pre-receive'>>\n-hook does on its standard input.\n+For a receive operation, this hook executes a single time at most.  It\n+takes no arguments, but for each ref successfully updated, it receives a\n+line on standard input that follows the same format as the\n+<<pre-receive,'pre-receive'>> hook.\n \n This hook does not affect the outcome of `git receive-pack`, as it\n is called after the real work is done.\n@@ -448,6 +448,9 @@ environment variables will not be set. If the client selects\n to use push options, but doesn't transmit any, the count variable\n will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.\n \n+See the link:git-receive-pack.html#_post_receive_hook[post-receive hook]\n+section in linkgit:git-receive-pack[1] for additional details.\n+\n [[post-update]]\n post-update\n ~~~~~~~~~~~\n\nbase-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\n-- \n2.45.2\n\n"},{"id":"498602","messageId":"xmqq8qy6jjdc.fsf@gitster.g","threadId":"61773","inReplyTo":"20240712224748.56843-1-jltobler@gmail.com","subject":"Re: [PATCH] doc: clarify post-receive hook behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-12T23:11:43Z","receivedAt":"2024-07-12T23:11:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler <jltobler@gmail.com> writes:\n\n> The `githooks` documentation mentions that the post-receive hook\n> executes once after git-receive-pack(1) updates all references and that\n> it also receives the same information as the pre-receive hook on\n> standard input. This is misleading though because the hook only\n> executes once if at least one of the attempted reference updates is\n> successful. Also, while each line provided on standard input is in the\n> same format as the pre-receive hook, the information received only\n> includes the set of references that were successfully updated.\n\nYup, it sounds like is a sensible design that gives the most useful\ninformation to the hook.\n\n> diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\n> index 06e997131b..f9eb396a79 100644\n> --- a/Documentation/githooks.txt\n> +++ b/Documentation/githooks.txt\n> @@ -415,13 +415,13 @@ post-receive\n>  \n>  This hook is invoked by linkgit:git-receive-pack[1] when it reacts to\n>  `git push` and updates reference(s) in its repository.\n> -It executes on the remote repository once after all the refs have\n> -been updated.\n> +It executes on the remote repository once if any of the attempted ref\n> +updates are successful.\n\nWe could instead say \"at least one of\", but \"any of\" should be fine.\nOK.\n\n> -This hook executes once for the receive operation.  \n> +For a receive operation, this hook executes a single time at most.  \n\nHmph, maybe we can strike this sentence as we already said \"once\" in\nthe previous paragraph.  The intention of the original description\nthat said \"only after\" was to convey two things:\n\n (1) it runs only once, and\n (2) it does not run before all the ref-update requests have been\n     processed (either successfully or unsuccessfully).  \n\nIf the \"only after\" was not serving the original purpose of\nconveying both of the two, then perhaps we should remove the word\n\"once\" from the previous paragraph instead and keep this sentence.\n\nMy preference is revert your \"once after\" -> \"once if\" to get back\nto the original \"once after\", and then remove \"this hook executes\nonce for the receive operaiton\" of the original, without adding your\n\"For a receieve ... at most\".\n\n    The hook executes on the remote repository once after all the\n    proposed ref updates are processed and if at least one ref is\n    updated as the result.\n\n> -It takes no\n> -arguments, but gets the same information as the\n> -<<pre-receive,'pre-receive'>>\n> -hook does on its standard input.\n> -It\n> +takes no arguments, but for each ref successfully updated, it receives a\n> +line on standard input that follows the same format as the\n> +<<pre-receive,'pre-receive'>> hook.\n\nThis part of the update is great.  The \"but\" there is annoying, but\nthat badness was inherited from the original and not a fault of this\npatch.  If I were writing it from scratch I would probably have said\nsomething like:\n\n    The hook takes no arguments.  It receives one line on standard\n    input for each ref that is successfully updated in the same\n    format as the pre-receive hook.\n\nThanks.\n"},{"id":"498690","messageId":"zftb6xcmweatgzmhl44k3z5f7ga3wt64eryen3pvgbb6dpqaae@74h5fz3ffo5q","threadId":"61773","inReplyTo":"xmqq8qy6jjdc.fsf@gitster.g","subject":"Re: [PATCH] doc: clarify post-receive hook behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-07-14T18:54:28Z","receivedAt":"2024-07-14T18:55:04Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 24/07/12 04:11PM, Junio C Hamano wrote:\n> Justin Tobler <jltobler@gmail.com> writes:\n> \n> > -This hook executes once for the receive operation.  \n> > +For a receive operation, this hook executes a single time at most.  \n> \n> Hmph, maybe we can strike this sentence as we already said \"once\" in\n> the previous paragraph.  The intention of the original description\n> that said \"only after\" was to convey two things:\n\nYa, I competely agree that this is repetetive and should be removed. \n\n> \n>  (1) it runs only once, and\n>  (2) it does not run before all the ref-update requests have been\n>      processed (either successfully or unsuccessfully).  \n> \n> If the \"only after\" was not serving the original purpose of\n> conveying both of the two, then perhaps we should remove the word\n> \"once\" from the previous paragraph instead and keep this sentence.\n> \n> My preference is revert your \"once after\" -> \"once if\" to get back\n> to the original \"once after\", and then remove \"this hook executes\n> once for the receive operaiton\" of the original, without adding your\n> \"For a receieve ... at most\".\n> \n>     The hook executes on the remote repository once after all the\n>     proposed ref updates are processed and if at least one ref is\n>     updated as the result.\n> \n\nThanks for the suggestion. This more clearly conveys the two points\nmentioned. Will add in V2.\n\n> > -It takes no\n> > -arguments, but gets the same information as the\n> > -<<pre-receive,'pre-receive'>>\n> > -hook does on its standard input.\n> > -It\n> > +takes no arguments, but for each ref successfully updated, it receives a\n> > +line on standard input that follows the same format as the\n> > +<<pre-receive,'pre-receive'>> hook.\n> \n> This part of the update is great.  The \"but\" there is annoying, but\n> that badness was inherited from the original and not a fault of this\n> patch.  If I were writing it from scratch I would probably have said\n> something like:\n> \n>     The hook takes no arguments.  It receives one line on standard\n>     input for each ref that is successfully updated in the same\n>     format as the pre-receive hook.\n> \n\nI also agree that it is better to break out these two statements. Will\nadapt this for V2. Thanks again.\n\n-Justin\n"},{"id":"498691","messageId":"20240714194626.29512-2-jltobler@gmail.com","threadId":"61773","inReplyTo":"20240712224748.56843-1-jltobler@gmail.com","subject":"[PATCH v2] doc: clarify post-receive hook behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-07-14T19:46:27Z","receivedAt":"2024-07-14T19:48:13Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"The `githooks` documentation mentions that the post-receive hook\nexecutes once after git-receive-pack(1) updates all references and that\nit also receives the same information as the pre-receive hook on\nstandard input. This is misleading though because the hook only\nexecutes once if at least one of the attempted reference updates is\nsuccessful. Also, while each line provided on standard input is in the\nsame format as the pre-receive hook, the information received only\nincludes the set of references that were successfully updated.\n\nUpdate the documentation to clarify these points and also provide a\nreference to the post-receive hook section of the `git-receive-pack`\ndocumentation which has additional information.\n\nSigned-off-by: Justin Tobler <jltobler@gmail.com>\n---\n\nGreetings again,\n\nThis is the second version of my patch for post-receive hook\ndocumentation updates. Thanks again for taking a look.\n\n-Justin\n\nChanges from v1:\n- Removed repetivitve statement about the hook being executed once.\n- Slightly reworded statements to improve clarity.\n\nRange-diff against v1:\n1:  e4824ba60d ! 1:  747e925dfc doc: clarify post-receive hook behavior\n    @@ Documentation/githooks.txt: post-receive\n      `git push` and updates reference(s) in its repository.\n     -It executes on the remote repository once after all the refs have\n     -been updated.\n    -+It executes on the remote repository once if any of the attempted ref\n    -+updates are successful.\n    ++The hook executes on the remote repository once after all the proposed\n    ++ref updates are processed and if at least one ref is updated as the\n    ++result.\n      \n     -This hook executes once for the receive operation.  It takes no\n     -arguments, but gets the same information as the\n     -<<pre-receive,'pre-receive'>>\n     -hook does on its standard input.\n    -+For a receive operation, this hook executes a single time at most.  It\n    -+takes no arguments, but for each ref successfully updated, it receives a\n    -+line on standard input that follows the same format as the\n    ++The hook takes no arguments.  It receives one line on standard input for\n    ++each ref that is successfully updated following the same format as the\n     +<<pre-receive,'pre-receive'>> hook.\n      \n      This hook does not affect the outcome of `git receive-pack`, as it\n\n Documentation/githooks.txt | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex 06e997131b..5459a40326 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -415,13 +415,13 @@ post-receive\n \n This hook is invoked by linkgit:git-receive-pack[1] when it reacts to\n `git push` and updates reference(s) in its repository.\n-It executes on the remote repository once after all the refs have\n-been updated.\n+The hook executes on the remote repository once after all the proposed\n+ref updates are processed and if at least one ref is updated as the\n+result.\n \n-This hook executes once for the receive operation.  It takes no\n-arguments, but gets the same information as the\n-<<pre-receive,'pre-receive'>>\n-hook does on its standard input.\n+The hook takes no arguments.  It receives one line on standard input for\n+each ref that is successfully updated following the same format as the\n+<<pre-receive,'pre-receive'>> hook.\n \n This hook does not affect the outcome of `git receive-pack`, as it\n is called after the real work is done.\n@@ -448,6 +448,9 @@ environment variables will not be set. If the client selects\n to use push options, but doesn't transmit any, the count variable\n will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.\n \n+See the link:git-receive-pack.html#_post_receive_hook[post-receive hook]\n+section in linkgit:git-receive-pack[1] for additional details.\n+\n [[post-update]]\n post-update\n ~~~~~~~~~~~\n\nbase-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\n-- \n2.45.2\n\n"},{"id":"498733","messageId":"xmqqfrsa7j4p.fsf@gitster.g","threadId":"61773","inReplyTo":"20240714194626.29512-2-jltobler@gmail.com","subject":"Re: [PATCH v2] doc: clarify post-receive hook behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-15T15:46:46Z","receivedAt":"2024-07-15T15:46:52Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler <jltobler@gmail.com> writes:\n\n> +See the link:git-receive-pack.html#_post_receive_hook[post-receive hook]\n> +section in linkgit:git-receive-pack[1] for additional details.\n\nUse of link:*.html to point to the HTML version of the manual page\nis questionable.  Do we have any example that uses such a link\nalready?  What would this line do to those who read the manual page,\nnot HTML, iow, \"git receive-pack --help -m\"?\n\nThe latter link using linkgit: is bog standard and perfectly fine.\n\nThanks.\n\n"},{"id":"498744","messageId":"dzdoaldgm5sk25ll57okroqcnhqurtoqmo7d5xsjnrjpgveqzx@63w4uav6jtd6","threadId":"61773","inReplyTo":"xmqqfrsa7j4p.fsf@gitster.g","subject":"Re: [PATCH v2] doc: clarify post-receive hook behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-07-15T18:22:36Z","receivedAt":"2024-07-15T18:23:13Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"On 24/07/15 08:46AM, Junio C Hamano wrote:\n> Justin Tobler <jltobler@gmail.com> writes:\n> \n> > +See the link:git-receive-pack.html#_post_receive_hook[post-receive hook]\n> > +section in linkgit:git-receive-pack[1] for additional details.\n> \n> Use of link:*.html to point to the HTML version of the manual page\n> is questionable.  Do we have any example that uses such a link\n> already?  What would this line do to those who read the manual page,\n> not HTML, iow, \"git receive-pack --help -m\"?\n\nThe manual page for git(1) makes use of link:*.html to point to HTML\ndocumentation.\n\n  - Documentation/git.txt\n  - https://git-scm.com/docs/git\n\nIn the manual page it appears to specify a path to HTML file in the\nNOTES section. I'm not sure this is a good thing though because the file\ncannot be expected to exist at the path.\n\n> The latter link using linkgit: is bog standard and perfectly fine.\n\nI think it makes the most sense to drop the link:*html used here and\njust rely on the linkgit: reference. I'll adjust this in v3. Thanks for\nthe feedback.\n\n-Justin\n"},{"id":"498746","messageId":"20240715183739.7808-1-jltobler@gmail.com","threadId":"61773","inReplyTo":"20240714194626.29512-2-jltobler@gmail.com","subject":"[PATCH v3] doc: clarify post-receive hook behavior","fromName":"Justin Tobler","fromEmail":"jltobler@gmail.com","sentAt":"2024-07-15T18:37:39Z","receivedAt":"2024-07-15T18:38:37Z","isPatch":true,"sender":{"key":"jltobler@gmail.com","avatar":"https://avatars.githubusercontent.com/u/53454972?v=4"},"body":"The `githooks` documentation mentions that the post-receive hook\nexecutes once after git-receive-pack(1) updates all references and that\nit also receives the same information as the pre-receive hook on\nstandard input. This is misleading though because the hook only\nexecutes once if at least one of the attempted reference updates is\nsuccessful. Also, while each line provided on standard input is in the\nsame format as the pre-receive hook, the information received only\nincludes the set of references that were successfully updated.\n\nUpdate the documentation to clarify these points and also provide a\nreference to the post-receive hook section of the `git-receive-pack`\ndocumentation which has additional information.\n\nSigned-off-by: Justin Tobler <jltobler@gmail.com>\n---\n\nGreetings again, \n\nThis is the third version of my patch to clarify documentation for the\npost-receive git hook. Thanks for taking a look.\n\nChanges since v2:\n- Removed added usage of link:*.html reference since links to HTML\n  documentation in the corresponding manual page are likely to be\n  broken. The provided linkgit: reference should be sufficient.\n\nRange-diff against v2:\n1:  747e925dfc ! 1:  963e3ddc83 doc: clarify post-receive hook behavior\n    @@ Documentation/githooks.txt: environment variables will not be set. If the client\n      to use push options, but doesn't transmit any, the count variable\n      will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.\n      \n    -+See the link:git-receive-pack.html#_post_receive_hook[post-receive hook]\n    -+section in linkgit:git-receive-pack[1] for additional details.\n    ++See the \"post-receive\" section in linkgit:git-receive-pack[1] for\n    ++additional details.\n     +\n      [[post-update]]\n      post-update\n\n Documentation/githooks.txt | 15 +++++++++------\n 1 file changed, 9 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/githooks.txt b/Documentation/githooks.txt\nindex 06e997131b..0397dec64d 100644\n--- a/Documentation/githooks.txt\n+++ b/Documentation/githooks.txt\n@@ -415,13 +415,13 @@ post-receive\n \n This hook is invoked by linkgit:git-receive-pack[1] when it reacts to\n `git push` and updates reference(s) in its repository.\n-It executes on the remote repository once after all the refs have\n-been updated.\n+The hook executes on the remote repository once after all the proposed\n+ref updates are processed and if at least one ref is updated as the\n+result.\n \n-This hook executes once for the receive operation.  It takes no\n-arguments, but gets the same information as the\n-<<pre-receive,'pre-receive'>>\n-hook does on its standard input.\n+The hook takes no arguments.  It receives one line on standard input for\n+each ref that is successfully updated following the same format as the\n+<<pre-receive,'pre-receive'>> hook.\n \n This hook does not affect the outcome of `git receive-pack`, as it\n is called after the real work is done.\n@@ -448,6 +448,9 @@ environment variables will not be set. If the client selects\n to use push options, but doesn't transmit any, the count variable\n will be set to zero, `GIT_PUSH_OPTION_COUNT=0`.\n \n+See the \"post-receive\" section in linkgit:git-receive-pack[1] for\n+additional details.\n+\n [[post-update]]\n post-update\n ~~~~~~~~~~~\n\nbase-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9\n-- \n2.45.2\n\n"},{"id":"498748","messageId":"xmqqjzhm3376.fsf@gitster.g","threadId":"61773","inReplyTo":"dzdoaldgm5sk25ll57okroqcnhqurtoqmo7d5xsjnrjpgveqzx@63w4uav6jtd6","subject":"Re: [PATCH v2] doc: clarify post-receive hook behavior","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-07-15T18:44:29Z","receivedAt":"2024-07-15T18:44:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Justin Tobler <jltobler@gmail.com> writes:\n\n> I think it makes the most sense to drop the link:*html used here and\n> just rely on the linkgit: reference. I'll adjust this in v3. Thanks for\n> the feedback.\n\nThat sounds like a sensible and conservative approach.\n\nThanks.\n"}]}