[v3] git-rebase.txt: add another hook to the hooks section, and explain more

Commit Message

John Passaro via GitGitGadget April 5, 2020, midnight UTC

From: Elijah Newren <[e-mail]>

For more discussion about these hooks, their history relative to rebase,
and logical consistency between different types of operations, see
  https://lore.kernel.org/git/[e-mail]/
and the links to some threads referenced therein.

Signed-off-by: Elijah Newren <[e-mail]>
---
    git-rebase.txt: add another hook to the hooks section, and explain more
    
    Changes since v2:
    
     * Corrections to the text pointed out by Phillip.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-749%2Fnewren%2Frebase-and-hooks-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-749/newren/rebase-and-hooks-v3
Pull-Request: https://github.com/git/git/pull/749

Range-diff vs v2:

 1:  45a5c1c1ff9 ! 1:  22fb6ff7080 git-rebase.txt: add another hook to the hooks section, and explain more
     @@ Documentation/git-rebase.txt: Hooks
      -while the merge backend has.  However, this was by accident of
      -implementation rather than by design.  Both backends should have the
      -same behavior, though it is not clear which one is correct.
     -+while the merge backend has.  In contrast, the apply backend has
     -+traditionally called the post-checkout hook while the merge backend
     -+has not.  However, the calling of these hooks in both cases was by
     -+accident of implementation rather than by design (both backends were
     -+originally implemented as shell scripts and happened to invoke other
     -+commands like 'git checkout' or 'git commit' that would call the
     -+hooks).  Both backends should have the same behavior, though it is not
     -+entirely clear which, if any, is correct.  We will likely make rebase
     -+stop calling either of these hooks in the future.
     ++while the merge backend has.  Both have called the post-checkout hook,
     ++though the merge backend has squelched its output.  Further, both
     ++backends only call the post-checkout hook with the starting point
     ++commit of the rebase, not the intermediate commits nor the final
     ++commit.  In each case, the calling of these hooks was by accident of
     ++implementation rather than by design (both backends were originally
     ++implemented as shell scripts and happened to invoke other commands
     ++like 'git checkout' or 'git commit' that would call the hooks).  Both
     ++backends should have the same behavior, though it is not entirely
     ++clear which, if any, is correct.  We will likely make rebase stop
     ++calling either of these hooks in the future.
       
       Interruptability
       ~~~~~~~~~~~~~~~~


 Documentation/git-rebase.txt | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)


base-commit: 274b9cc25322d9ee79aa8e6d4e86f0ffe5ced925

Patch

diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
index f7a6033607f..5a756b5b3a6 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -684,9 +684,17 @@  Hooks
 ~~~~~
 
 The apply backend has not traditionally called the post-commit hook,
-while the merge backend has.  However, this was by accident of
-implementation rather than by design.  Both backends should have the
-same behavior, though it is not clear which one is correct.
+while the merge backend has.  Both have called the post-checkout hook,
+though the merge backend has squelched its output.  Further, both
+backends only call the post-checkout hook with the starting point
+commit of the rebase, not the intermediate commits nor the final
+commit.  In each case, the calling of these hooks was by accident of
+implementation rather than by design (both backends were originally
+implemented as shell scripts and happened to invoke other commands
+like 'git checkout' or 'git commit' that would call the hooks).  Both
+backends should have the same behavior, though it is not entirely
+clear which, if any, is correct.  We will likely make rebase stop
+calling either of these hooks in the future.
 
 Interruptability
 ~~~~~~~~~~~~~~~~