[nongnu] elpa/git-commit e37c9ea4de 1/4: Make discouraged use of git-commit-mode-hook safer and more convenient

[ELPA Syncer]

branch: elpa/git-commit
commit e37c9ea4dec249ee95672dfba280e94ac870e263
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    Make discouraged use of git-commit-mode-hook safer and more convenient
    
    `git-commit-mode' is a minor-mode, as opposed to being the major-mode
    used in commit message buffers (as its name may suggest, and many users
    seem to assume).
    
    We therefore decided a long time ago that `git-commit-hook-mode' should
    not be used and provided `git-commit-setup-hook' as an alternative.
    
    Despite that, users keep trying to use it anyway, and often that leads
    to issues.  It doesn't help that this hook has a generic generated
    docstring, which does nothing to discourage its use.
    
    Instead of continuing to tell users not to use this hook, one by one, or
    taking more drastic measures to prevent its use, just make it an alias
    for `git-commit-setup-hook'.  (It is also too late to instead remove
    *that* hook.)
    
    Prevent `git-commit-mode-hook' from being run when `git-commit-mode' is
    enabled.  It is now run a bit later under the `git-commit-setup-hook'
    name, while also demoting errors.  Demoting errors is important, because
    errors that occur here, are (1) hard to debug (because there is no
    backtrace), (2) common (due to user errors), and (3) they outright
    prevent committing.
    
    It also makes a difference that the hook is run slightly later now.
    Some things that would fail at the earlier time, actually work at the
    later time.  For example, functions that rely on font-lock being setup
    (which is reasonable to do if you wrongly assume that `git-commit-mode'
    is a major-mode), as many seem to do, only works at the later time.
    
    Also move the call to `git-commit-mode' itself further down.
    
    In summary, it seems safest *and* most convenient, to just let users
    add to the same hook under two different names, and to run it at the
    appropriate time, while demoting errors.
---
 lisp/git-commit.el | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/lisp/git-commit.el b/lisp/git-commit.el
index 4b49730804..ad672a6b35 100644
--- a/lisp/git-commit.el
+++ b/lisp/git-commit.el
@@ -213,6 +213,10 @@ The major mode configured here is turned on by the minor 
mode
 ;;;###autoload                   fundamental-mode
 ;;;###autoload                   git-commit-elisp-text-mode))))
 
+(defvaralias 'git-commit-mode-hook 'git-commit-setup-hook
+  "This variable is an alias for `git-commit-setup-hook' (which see).
+Also note that `git-commit-mode' (which see) is not a major-mode.")
+
 (defcustom git-commit-setup-hook
   '(git-commit-save-message
     git-commit-setup-changelog-support
@@ -644,7 +648,6 @@ Used as the local value of `header-line-format', in buffer 
using
       (magit-wip-maybe-add-commit-hook)))
   (setq with-editor-cancel-message
         #'git-commit-cancel-message)
-  (git-commit-mode 1)
   (git-commit-setup-font-lock)
   (git-commit-prepare-message-ring)
   (when (boundp 'save-place)
@@ -653,6 +656,8 @@ Used as the local value of `header-line-format', in buffer 
using
     (goto-char (point-min))
     (when (looking-at "\\`\\(\\'\\|\n[^\n]\\)")
       (open-line 1)))
+  (let ((git-commit-mode-hook nil))
+    (git-commit-mode 1))
   (with-demoted-errors "Error running git-commit-setup-hook: %S"
     (run-hooks 'git-commit-setup-hook))
   (when git-commit-usage-message
@@ -682,7 +687,9 @@ Used as the local value of `header-line-format', in buffer 
using
 (define-minor-mode git-commit-mode
   "Auxiliary minor mode used when editing Git commit messages.
 This mode is only responsible for setting up some key bindings.
-Don't use it directly, instead enable `global-git-commit-mode'."
+Don't use it directly; instead enable `global-git-commit-mode'.
+Variable `git-commit-major-mode' controls which major-mode is
+used."
   :lighter "")
 
 (put 'git-commit-mode 'permanent-local t)