refactor!(vc-gutter): drop git-gutter for diff-hl

BREAKING CHANGE: This removes git-gutter as an implementation for the
`:ui vc-gutter` module, leaving only the diff-hl implementation. There
are no longer any +git-gutter or +diff-hl flags for this module. Users
don't have to do anything to keep the vc gutter, unless they prefer
git-gutter for any reason (in which case they'll need to install and set
it up themselves).

This has been planned for some time, because of a roadmap goal for Doom
to lean into native/built-in functionality where it's equal or better
than the third party alternatives. diff-hl relies on the built-in vc.el
library instead of talking to git directly (thus expanding support to
whatever VCS's vc.el supports, and not git alone), which also means it
can take advantage of its caching and other user configuration for
vc.el. Overall, it is faster and lighter.

What I've also been waiting for was a stage-hunk command, similar to
git-gutter:stage-hunk, which arrived in dgutov/diff-hl@a0560551cd and
dgutov/diff-hl@133538973b, and have evolved since.

Ref: dgutov/diff-hl@a0560551cd
Ref: dgutov/diff-hl@133538973b
Ref: https://github.com/orgs/doomemacs/projects/5/views/1?pane=issue&itemId=58747789

lisp/demos.org

@@ -64,8 +64,8 @@ are great, but this file exists to add demos for Doom's API and beyond.
 (after! helm ...)
 
 ;; An unquoted list of package symbols (i.e. BODY is evaluated once both magit
-;; and git-gutter have loaded)
-(after! (magit git-gutter) ...)
+;; and diff-hl have loaded)
+(after! (magit diff-hl) ...)
 
 ;; An unquoted, nested list of compound package lists, using any combination of
 ;; :or/:any and :and/:all

lisp/doom-keybinds.el

@@ -82,7 +82,7 @@ and Emacs states, and for non-evil users.")
 ;; 1. Quit active states; e.g. highlights, searches, snippets, iedit,
 ;;    multiple-cursors, recording macros, etc.
 ;; 2. Close popup windows remotely (if it is allowed to)
-;; 3. Refresh buffer indicators, like git-gutter and flycheck
+;; 3. Refresh buffer indicators, like diff-hl and flycheck
 ;; 4. Or fall back to `keyboard-quit'
 ;;
 ;; And it should do these things incrementally, rather than all at once. And it

lisp/doom-lib.el

@@ -641,8 +641,8 @@ is:
     (after! (:and package-a package-b ...) BODY...)
     (after! (:and package-a (:or package-b package-c) ...) BODY...)
 - An unquoted list of package symbols (i.e. BODY is evaluated once both magit
-  and git-gutter have loaded)
-    (after! (magit git-gutter) BODY...)
+  and diff-hl have loaded)
+    (after! (magit diff-hl) BODY...)
   If :or/:any/:and/:all are omitted, :and/:all are implied.
 
 This emulates `eval-after-load' with a few key differences:

lisp/doom-ui.el

@@ -242,7 +242,7 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 ;;; Fringes
 
 ;; Reduce the clutter in the fringes; we'd like to reserve that space for more
-;; useful information, like git-gutter and flycheck.
+;; useful information, like diff-hl and flycheck.
 (setq indicate-buffer-boundaries nil
       indicate-empty-lines nil)
 

modules/editor/evil/+commands.el

@@ -39,7 +39,7 @@
 (evil-ex-define-cmd "gstage"      #'magit-stage)
 (evil-ex-define-cmd "gunstage"    #'magit-unstage)
 (evil-ex-define-cmd "gblame"      #'magit-blame)
-(evil-ex-define-cmd "grevert"     #'git-gutter:revert-hunk)
+(evil-ex-define-cmd "grevert"     #'+vc-gutter/revert-hunk)
 
 ;;; Dealing with buffers
 (evil-ex-define-cmd "k[ill]"      #'doom/kill-current-buffer)

modules/editor/format/config.el

@@ -82,6 +82,6 @@ This is controlled by `+format-on-save-disabled-modes'."
        (save-excursion
          (font-lock-fontify-region web-mode-scan-beg web-mode-scan-end)))))
 
- (defun +format--refresh-git-gutter-h ()
+ (defun +format--refresh-vc-gutter-h ()
    (when (fboundp '+vc-gutter-update-h)
      (+vc-gutter-update-h))))

modules/input/layout/+azerty.el

@@ -28,8 +28,8 @@
     :desc "Next buffer" "è" #'next-buffer)
    (:prefix-map ("g" . "git")
     (:when (modulep! :ui vc-gutter)
-     :desc "Jump to previous hunk" "é" #'git-gutter:previous-hunk
-     :desc "Jump to next hunk" "è" #'git-gutter:next-hunk))))
+     :desc "Jump to previous hunk" "é" #'+vc-gutter/previous-hunk
+     :desc "Jump to next hunk" "è" #'+vc-gutter/next-hunk))))
 
 (defun +layout-remap-evil-keys-for-azerty-h ()
   (map! :nv "à" #'evil-execute-macro
@@ -48,8 +48,8 @@
         :m  "èy"    #'+evil:c-string-encode
         :m  "éy"    #'+evil:c-string-decode
         (:when (modulep! :ui vc-gutter)
-         :m "èd"   #'git-gutter:next-hunk
-         :m "éd"   #'git-gutter:previous-hunk)
+         :m "èd"   #'+vc-gutter/next-hunk
+         :m "éd"   #'+vc-gutter/previous-hunk)
         (:when (modulep! :ui hl-todo)
          :m "èt"   #'hl-todo-next
          :m "ét"   #'hl-todo-previous)

modules/input/layout/+bepo.el

@@ -54,8 +54,8 @@ In all cases, 'h' functions go to 'c' and 'l' ones go to 'r' so the navigation k
          :desc "Jump to documentation"     "S"  #'+lookup/documentation)
         (:prefix-map ("g" . "git")
          (:when (modulep! :ui vc-gutter)
-          :desc "Jump to next hunk"        ")"  #'git-gutter:next-hunk
-          :desc "Jump to previous hunk"    "("  #'git-gutter:previous-hunk))
+          :desc "Jump to next hunk"        ")"  #'+vc-gutter/next-hunk
+          :desc "Jump to previous hunk"    "("  #'+vc-gutter/previous-hunk))
         (:prefix-map ("p" . "project")
          :desc "Browse other project"      "»"  #'doom/browse-in-other-project)))
 

modules/lang/org/autoload/org-export.el

@@ -49,6 +49,6 @@ properties and font-locking et all)."
      (+org--yank-html-buffer (markdown)))
     (_
      ;; Omit after/before-string overlay properties in htmlized regions, so we
-     ;; don't get fringe characters for things like flycheck or git-gutter.
+     ;; don't get fringe characters for things like flycheck or diff-hl
      (letf! (defun htmlize-add-before-after-strings (_beg _end text) text)
        (ox-clip-formatted-copy beg end)))))

modules/tools/magit/autoload.el

@@ -108,7 +108,7 @@ modified."
 
 ;;;###autoload
 (defun +magit-revert-buffer-maybe-h ()
-  "Update `vc' and `git-gutter' if out of date."
+  "Update `vc' and `diff-hl' if out of date."
   (when +magit--stale-p
     (+magit--revert-buffer (current-buffer))))
 

modules/ui/doom/README.org

@@ -8,7 +8,6 @@ This module gives Doom its signature look: powered by the [[doom-package:doom-th
 (loosely inspired by [[https://github.com/atom/one-dark-syntax][Atom's One Dark theme]]) and [[doom-package:solaire-mode]]. Includes:
 
 - A custom folded-region indicator for [[doom-package:hideshow]].
-- "Thin bar" fringe bitmaps for [[doom-package:git-gutter-fringe]].
 - File-visiting buffers are slightly brighter (thanks to [[doom-package:solaire-mode]]).
 
 ** Maintainers

modules/ui/vc-gutter/README.org

@@ -13,44 +13,32 @@ Supports Git, Svn, Hg, and Bzr.
 [[doom-contrib-maintainer:][Become a maintainer?]]
 
 ** Module flags
-- +diff-hl ::
-  Use [[doom-package:diff-hl]] instead of git-gutter to power the VC gutter. It is a little
-  faster, but is slightly more prone to visual glitching. [[doom-package:diff-hl]] is intended to
-  replace git-gutter at some point in the future.
 - +pretty ::
-  Apply some stylistic defaults to the fringe, enabling thin bars in the fringe.
-  This look takes after the modern look of git-gutter in VSCode and Sublime
-  Text, without sacrificing on fringe width (which squeeze other indicators,
-  like flycheck's, flymake's, or flyspell's). However, this will look bad with
-  themes that invert the foreground/background of either git-gutter's or
-  diff-hl's faces (like modus-themes does).
+  Apply some stylistic defaults to the fringe that present the diff in the
+  fringe as thin bars, taking after the modern look of the git-gutter plugin in
+  VSCode and Sublime Text. However, this will look bad with themes that invert
+  the foreground/background of diff-hl's faces (like modus-themes does).
 
 ** Packages
-- [[doom-package:git-gutter-fringe]] unless [[doom-module:+diff-hl]]
-- [[doom-package:diff-hl]] if [[doom-module:+diff-hl]]
+- [[doom-package:diff-hl]]
 
 ** Hacks
 - The VC gutter will be updated when pressing ESC, leaving insert mode (evil
   users), or refocusing the frame or window where it is active.
 - If [[doom-module:+pretty]] is enabled
-  - The fringes that both git-gutter-fringe and diff-hl define will be replaced
-    with a set of thin bars. This achieves a slicker look closer to git-gutter's
-    appearance in VSCode or Sublime Text, but may look weird for themes that
-    swap their faces' :foreground and :background (like modus-themes).
+  - The fringes that diff-hl define will be replaced with a set of thin bars.
+    This achieves a slicker look closer to git-gutter's appearance in VSCode or
+    Sublime Text, but may look weird for themes that swap their faces'
+    :foreground and :background (like modus-themes).
   - The fringes are moved to the outside of the margins (closest to the frame
     edge), so they have some breathing space away from the buffer's contents.
-- If [[doom-package:+diff-hl]] is enabled:
-  - ~diff-hl-revert-hunk~ displays a preview popup of the hunk being reverted.
-    It takes up ~50% of the frame, by default, whether you're reverting 2 lines
-    or 20. Since this isn't easily customized, it has been advised to shrink
-    this popup to the side of its contents.
-  - ~diff-hl-revert-hunk~ will sometimes move the cursor to an unexpected
-    location (the bounds of hunks, is my guess), but this is not intuitive and
-    often unexpected. Cursor movements have been suppressed for it.
-- If +diff-hl is *not* enabled:
-  - Sometimes, ~git-gutter:next-hunk~ and ~git-gutter:previous-hunk~ get
-    confused about the order of hunks. They have been advised to fix this
-    (although the hack is a little inefficient).
+- ~diff-hl-revert-hunk~ displays a preview popup of the hunk being reverted.
+  It takes up ~50% of the frame, by default, whether you're reverting 2 lines
+  or 20. Since this isn't easily customized, it has been advised to shrink
+  this popup to the side of its contents.
+- ~diff-hl-revert-hunk~ will sometimes move the cursor to an unexpected
+  location (the bounds of hunks, is my guess), but this is not intuitive and
+  often unexpected. Cursor movements have been suppressed for it.
 
 ** TODO Changelog
 # This section will be machine generated. Don't edit it by hand.

modules/ui/vc-gutter/autoload/diff-hl.el

@@ -1,11 +1,22 @@
 ;;; ui/vc-gutter/autoload/diff-hl.el -*- lexical-binding: t; -*-
-;;;###if (modulep! +diff-hl)
 
 ;;;###autoload
 (defalias '+vc-gutter/stage-hunk #'diff-hl-stage-current-hunk)
 ;;;###autoload
-(defalias '+vc-gutter/revert-hunk #'diff-hl-revert-hunk)
-;;;###autoload
 (defalias '+vc-gutter/next-hunk #'diff-hl-next-hunk)
 ;;;###autoload
 (defalias '+vc-gutter/previous-hunk #'diff-hl-previous-hunk)
+
+(defvar vc-suppress-confirm)
+;;;###autoload
+(defun +vc-gutter/revert-hunk (&optional no-prompt)
+  "Invoke `diff-hl-revert-hunk'."
+  (interactive "P")
+  (let ((vc-suppress-confirm (if no-prompt t)))
+    (call-interactively #'diff-hl-revert-hunk)))
+
+;;;###autoload
+(defun +vc-gutter/save-and-revert-hunk ()
+  "Invoke `diff-hl-revert-hunk' with `vc-suppress-confirm' set."
+  (interactive)
+  (+vc-gutter/revert-hunk t))

modules/ui/vc-gutter/autoload/git-gutter.el

@@ -1,11 +0,0 @@
-;;; ui/vc-gutter/autoload/vc-gutter.el -*- lexical-binding: t; -*-
-;;;###if (not (modulep! +diff-hl))
-
-;;;###autoload
-(defalias '+vc-gutter/stage-hunk #'git-gutter:stage-hunk)
-;;;###autoload
-(defalias '+vc-gutter/revert-hunk #'git-gutter:revert-hunk)
-;;;###autoload
-(defalias '+vc-gutter/next-hunk #'git-gutter:next-hunk)
-;;;###autoload
-(defalias '+vc-gutter/previous-hunk #'git-gutter:previous-hunk)

modules/ui/vc-gutter/config.el

@@ -1,13 +1,5 @@
 ;;; ui/vc-gutter/config.el -*- lexical-binding: t; -*-
 
-;; TODO Implement me
-(defvar +vc-gutter-in-margin nil
-  "If non-nil, use the margin for diffs instead of the fringe.")
-
-(defvar +vc-gutter-in-remote-files nil
-  "If non-nil, enable the vc gutter in remote files (e.g. open through TRAMP).")
-
-
 ;;
 ;;; Default styles
 
@@ -23,36 +15,28 @@
   ;;   having to shrink the fringe and sacrifice precious space for other fringe
   ;;   indicators (like flycheck or flyspell).
   ;; REVIEW: Extract these into a package with faces that themes can target.
-  (if (not (modulep! +diff-hl))
-      (after! git-gutter-fringe
-        (define-fringe-bitmap 'git-gutter-fr:added [224]
-          nil nil '(center repeated))
-        (define-fringe-bitmap 'git-gutter-fr:modified [224]
-          nil nil '(center repeated))
-        (define-fringe-bitmap 'git-gutter-fr:deleted [128 192 224 240]
-          nil nil 'bottom))
-    (defadvice! +vc-gutter-define-thin-bitmaps-a (&rest args)
-      :override #'diff-hl-define-bitmaps
-      (define-fringe-bitmap 'diff-hl-bmp-middle [224] nil nil '(center repeated))
-      (define-fringe-bitmap 'diff-hl-bmp-delete [240 224 192 128] nil nil 'top))
-    (defun +vc-gutter-type-face-fn (type _pos)
-      (intern (format "diff-hl-%s" type)))
-    (defun +vc-gutter-type-at-pos-fn (type _pos)
-      (if (eq type 'delete)
-          'diff-hl-bmp-delete
-        'diff-hl-bmp-middle))
-    (advice-add #'diff-hl-fringe-bmp-from-pos  :override #'+vc-gutter-type-at-pos-fn)
-    (advice-add #'diff-hl-fringe-bmp-from-type :override #'+vc-gutter-type-at-pos-fn)
-    (setq diff-hl-draw-borders nil)
-    (add-hook! 'diff-hl-mode-hook
-      (defun +vc-gutter-fix-diff-hl-faces-h ()
-        (mapc (doom-rpartial #'set-face-background nil)
-              '(diff-hl-insert
-                diff-hl-delete
-                diff-hl-change)))))
+  (defadvice! +vc-gutter-define-thin-bitmaps-a (&rest args)
+    :override #'diff-hl-define-bitmaps
+    (define-fringe-bitmap 'diff-hl-bmp-middle [224] nil nil '(center repeated))
+    (define-fringe-bitmap 'diff-hl-bmp-delete [240 224 192 128] nil nil 'top))
+  (defun +vc-gutter-type-face-fn (type _pos)
+    (intern (format "diff-hl-%s" type)))
+  (defun +vc-gutter-type-at-pos-fn (type _pos)
+    (if (eq type 'delete)
+        'diff-hl-bmp-delete
+      'diff-hl-bmp-middle))
+  (advice-add #'diff-hl-fringe-bmp-from-pos  :override #'+vc-gutter-type-at-pos-fn)
+  (advice-add #'diff-hl-fringe-bmp-from-type :override #'+vc-gutter-type-at-pos-fn)
+  (setq diff-hl-draw-borders nil)
+  (add-hook! 'diff-hl-mode-hook
+    (defun +vc-gutter-fix-diff-hl-faces-h ()
+      (mapc (doom-rpartial #'set-face-background nil)
+            '(diff-hl-insert
+              diff-hl-delete
+              diff-hl-change))))
 
-  ;; FIX: To minimize overlap between flycheck indicators and git-gutter/diff-hl
-  ;;   indicators in the left fringe.
+  ;; FIX: To minimize overlap between flycheck indicators and diff-hl indicators
+  ;;   in the left fringe.
   (after! flycheck
     ;; Let diff-hl have left fringe, flycheck can have right fringe
     (setq flycheck-indication-mode 'right-fringe)
@@ -61,99 +45,10 @@
       [16 48 112 240 112 48 16] nil nil 'center)))
 
 
-;;
-;;; git-gutter
-
-(use-package! git-gutter
-  :unless (modulep! +diff-hl)
-  :commands git-gutter:revert-hunk git-gutter:stage-hunk git-gutter:previous-hunk git-gutter:next-hunk
-  :init
-  (add-hook! 'find-file-hook
-    (defun +vc-gutter-init-maybe-h ()
-      "Enable `git-gutter-mode' in the current buffer.
-If the buffer doesn't represent an existing file, `git-gutter-mode's activation
-is deferred until the file is saved. Respects `git-gutter:disabled-modes'."
-      (let ((file-name (buffer-file-name (buffer-base-buffer))))
-        (cond
-         ((and (file-remote-p (or file-name default-directory))
-               (not +vc-gutter-in-remote-files)))
-         ;; UX: If not a valid file, wait until it is written/saved to activate
-         ;;   git-gutter.
-         ((not (and file-name (vc-backend file-name)))
-          (add-hook 'after-save-hook #'+vc-gutter-init-maybe-h nil 'local))
-         ;; UX: Allow git-gutter or git-gutter-fringe to activate based on the
-         ;;   type of frame we're in. This allows git-gutter to work for silly
-         ;;   geese who open both tty and gui frames from the daemon.
-         ((if (and (display-graphic-p)
-                   (require 'git-gutter-fringe nil t))
-              (setq-local git-gutter:init-function      #'git-gutter-fr:init
-                          git-gutter:view-diff-function #'git-gutter-fr:view-diff-infos
-                          git-gutter:clear-function     #'git-gutter-fr:clear
-                          git-gutter:window-width -1)
-            (setq-local git-gutter:init-function      'nil
-                        git-gutter:view-diff-function #'git-gutter:view-diff-infos
-                        git-gutter:clear-function     #'git-gutter:clear-diff-infos
-                        git-gutter:window-width 1))
-          (unless (memq major-mode git-gutter:disabled-modes)
-            (git-gutter-mode +1)
-            (remove-hook 'after-save-hook #'+vc-gutter-init-maybe-h 'local)))))))
-
-  ;; UX: Disable in Org mode, as per syl20bnr/spacemacs#10555 and
-  ;;   syohex/emacs-git-gutter#24. Apparently, the mode-enabling function for
-  ;;   global minor modes gets called for new buffers while they are still in
-  ;;   `fundamental-mode', before a major mode has been assigned. I don't know
-  ;;   why this is the case, but adding `fundamental-mode' here fixes the issue.
-  (setq git-gutter:disabled-modes '(fundamental-mode image-mode pdf-view-mode))
-  :config
-  (set-popup-rule! "^\\*git-gutter" :select nil :size '+popup-shrink-to-fit)
-
-  ;; PERF: Only enable the backends that are available, so it doesn't have to
-  ;;   check when opening each buffer.
-  (setq git-gutter:handled-backends
-        (cons 'git (cl-remove-if-not #'executable-find (list 'hg 'svn 'bzr)
-                                     :key #'symbol-name)))
-
-  ;; UX: update git-gutter on focus (in case I was using git externally)
-  (add-hook 'focus-in-hook #'git-gutter:update-all-windows)
-
-  ;; Stop git-gutter doing things when we don't want
-  (remove-hook 'post-command-hook #'git-gutter:post-command-hook)
-  (advice-remove #'quit-window #'git-gutter:quit-window)
-  (advice-remove #'switch-to-buffer #'git-gutter:switch-to-buffer)
-
-  (add-hook! '(doom-escape-hook doom-switch-window-hook) :append
-    (defun +vc-gutter-update-h (&rest _)
-      "Refresh git-gutter on ESC. Return nil to prevent shadowing other
-`doom-escape-hook' hooks."
-      (ignore (or (memq this-command '(git-gutter:stage-hunk
-                                       git-gutter:revert-hunk))
-                  inhibit-redisplay
-                  (if git-gutter-mode
-                      (git-gutter)
-                    (+vc-gutter-init-maybe-h))))))
-  ;; UX: update git-gutter when using magit commands
-  (advice-add #'magit-stage-file   :after #'+vc-gutter-update-h)
-  (advice-add #'magit-unstage-file :after #'+vc-gutter-update-h)
-
-  ;; UX: update git-gutter after reverting a buffer
-  (add-hook 'after-revert-hook #'+vc-gutter-update-h)
-
-  ;; FIX: stop git-gutter:{next,previous}-hunk from jumping to random hunks.
-  (defadvice! +vc-gutter--fix-linearity-of-hunks-a (diffinfos is-reverse)
-    :override #'git-gutter:search-near-diff-index
-    (cl-position-if (let ((lineno (line-number-at-pos))
-                          (fn (if is-reverse #'> #'<)))
-                      (lambda (line) (funcall fn lineno line)))
-                    diffinfos
-                    :key #'git-gutter-hunk-start-line
-                    :from-end is-reverse)))
-
-
 ;;
 ;;; diff-hl
 
 (use-package! diff-hl
-  :when (modulep! +diff-hl)
   :hook (find-file    . diff-hl-mode)
   :hook (vc-dir-mode  . diff-hl-dir-mode)
   :hook (dired-mode   . diff-hl-dired-mode)
@@ -162,8 +57,6 @@ is deferred until the file is saved. Respects `git-gutter:disabled-modes'."
   :config
   (set-popup-rule! "^\\*diff-hl" :select nil :size '+popup-shrink-to-fit)
 
-  ;; PERF: reduce load on remote
-  (defvaralias 'diff-hl-disable-on-remote '+vc-gutter-in-remote-files)
   ;; PERF: A slightly faster algorithm for diffing.
   (setq vc-git-diff-switches '("--histogram"))
   ;; PERF: Slightly more conservative delay before updating the diff
@@ -185,7 +78,7 @@ is deferred until the file is saved. Respects `git-gutter:disabled-modes'."
           :n "{" #'diff-hl-show-hunk-previous
           :n "}" #'diff-hl-show-hunk-next
           :n "S" #'diff-hl-show-hunk-stage-hunk))
-  ;; UX: Refresh git-gutter on ESC or refocusing the Emacs frame.
+  ;; UX: Refresh gutter on ESC or refocusing the Emacs frame.
   (add-hook! '(doom-escape-hook doom-switch-window-hook) :append
     (defun +vc-gutter-update-h (&rest _)
       "Return nil to prevent shadowing other `doom-escape-hook' hooks."

modules/ui/vc-gutter/packages.el

@@ -1,6 +1,4 @@
 ;; -*- no-byte-compile: t; -*-
 ;;; ui/vc-gutter/packages.el
 
-(if (modulep! +diff-hl)
-    (package! diff-hl :pin "11f3113e790526d5ee00f61f8e7cd0d01e323b2e")
-  (package! git-gutter-fringe :pin "648cb5b57faec55711803cdc9434e55a733c3eba"))
+(package! diff-hl :pin "11f3113e790526d5ee00f61f8e7cd0d01e323b2e")