Blamer.el

A git blame plugin for emacs inspired by VS Code’s GitLens plugin and Vim plugin

Preview

Install

Emacs 27.1 is required.

Melpa

(use-package blamer
  :ensure t
  :bind (("s-i" . blamer-show-commit-info)
         ("C-c i" . ("s-i" . blamer-show-posframe-commit-info)))
  :defer 20
  :custom
  (blamer-idle-time 0.3)
  (blamer-min-offset 70)
  :custom-face
  (blamer-face ((t :foreground "#7a88cf"
                    :background nil
                    :height 140
                    :italic t)))
  :config
  (global-blamer-mode 1))

quelpa

(use-package blamer
  :quelpa ((blamer :fetcher github :repo "artawower/blamer.el") :upgrade t)
  :bind (("s-i" . blamer-show-commit-info)
         ("C-c i" . ("s-i" . blamer-show-posframe-commit-info)))
  :custom
  (blamer-idle-time 0.3)
  (blamer-min-offset 70)
  :custom-face
  (blamer-face ((t :foreground "#7a88cf"
                    :background nil
                    :height 140
                    :italic t)))
  :config
  (global-blamer-mode 1))

Straight

(use-package blamer
  :straight (:host github :repo "artawower/blamer.el")
  :bind (("s-i" . blamer-show-commit-info))
  :custom
  (blamer-idle-time 0.3)
  (blamer-min-offset 70)
  :custom-face
  (blamer-face ((t :foreground "#7a88cf"
                    :background nil
                    :height 140
                    :italic t)))
  :config
  (global-blamer-mode 1))

doom

packages.el

(package! blamer)
;; or
(package! blamer :recipe (:host github :repo "artawower/blamer.el"))

config.el

(use-package blamer
  :bind (("s-i" . blamer-show-commit-info))
  :defer 20
  :custom
  (blamer-idle-time 0.3)
  (blamer-min-offset 70)
  :custom-face
  (blamer-face ((t :foreground "#7a88cf"
                    :background nil
                    :height 140
                    :italic t)))
  :config
  (global-blamer-mode 1))

Customization

Blamer view

Current style for blame messages, now can be overlay and overlay-right. (setq blamer-view 'overlay)

Template for author name

(setq blamer-author-formatter " ✎ %s ")

Template for datetime

(setq blamer-datetime-formatter "[%s]")

Template for commit message

(setq blamer-commit-formatter " ● %s")

All formatters can be nil.

Template for format entire message.

If your would like to wrap whole message, or add special prefix before blame text you can use (setq blamer-entire-formatter "<%>")

Time before blame showing

(setq blamer-idle-time 0.5)

Minimum offset from start from line

(setq blamer-min-offset 40)

Prettify time

(setq blamer-prettify-time-p t) Will format time line (2 days ago/1 week ago/Yesterday etc)

Blamer type

(setq blamer-type 'both) Can accept

• =’selected= - blamer will show commit info for every selected line.
• =’visual= - blamer will show info only about one line.
• =’both= - works with both states.
• =’overlay-popup= - nice overlay popup (see images/blamer-pretty-popup-dark.jpg)
• =’posframe-popup= - posframe popup (see images/posframe.png) Warning The ‘overlay-popup feature highly dependent on you custom fonts, it may have worse alignment.

Overlay popup position

blamer--overlay-popup-position - is position for the overlay popup, it could be:

• =’bottom=
• =’top=
• =’smart= - will choose the better popup position, in most cases it will prefer center

Max blamer lines in selected mode

If more then 30 lines will selected, blamer will not try to execute git commands. (setq blamer-max-lines 30)

Message for uncommitted changes

(setq blamer-uncommitted-changes-message "NO COMMITTED")

Max commit message length

If line has length more then this value, text will be truncated (setq blamer-max-commit-message-length 10)

Prefer blamer face

If you want to disable automatic background detection you can always use blamer face (setq blamer-smart-background-p nil)

Tooltip

You can turn on a tooltip when hovering over a commit, by settings blamer-tooltip-function This variably can apply default functions (setq blamer-tooltip-function 'blamer-tooltip-keybindings) - will show keybindings for current commit message (setq blamer-tooltip-function 'blamer-tooltip-commit-message) - show commit message about current line (it could be helpfull when blamer-commit-formatter is empty) (setq blamer-tooltip-function 'blamer-tooltip-author-info) - show information about author Also you can write own function with first argumens as commit-info plist, or set this variable to null, that mean tooltip is disabled

For example, you can write function for showing commit datetime inside tooltip:

(defun my-blamer-tooltip-func (commit-info)
  (let ((commit-date (plist-get commit-info :commit-date))
        (commit-time (plist-get commit-info :commit-time)))
    (message "%s" commit-info)
    (format "%s - %s" commit-date commit-time)))

(setq blamer-tooltip-function 'my-blamer-tooltip-func)

User avatar

Available in the posframe for github and gitlab only!

blamer-show-avatar-p - if you want to show the user avatar in the posframe popup, you can set this variable to t.

If you have an incorrect view of the avatar or line breaks, try to play with these variables.

blamer-avatar-size - size of the avatar, default is 96px.

blamer-avatar-ratio - the ratio of the avatar, default is 3x3.

blamer-default-avatar-url - default fallback URL for not found avatars or users.

blamer-avatar-folder - folder for saving avatars, default is ~/.blamer/avatars/

blamer-avatar-regexps-uploaders-alist - list of regexp patterns as car, and API URL and uploader fn as cdr.

Useful for self-hosted Gitlab or GitHub instances.

Interactive binding

You can bind the mouse click event and pass custom handler. Where the handler is callback function with commit-info arg. commit-info consist of:

:commit-hash - hash of clicked commit :commit-author - author name after formatting :raw-commit-author - raw author username if exist. :commit-date - date of commit. (string field) :commit-time - commit’s time. (string field) :commit-message - message of commit. If not exist will be get from blamer-uncommitted-changes-message :raw-commit-message - full message of commit. For example, if we want to open magit diff by left click, and browse remote by right click we can use this code (magit and forge have to be installed):

(defun blamer-callback-show-commit-diff (commit-info)
  (interactive)
  (let ((commit-hash (plist-get commit-info :commit-hash)))
    (when commit-hash
      (magit-show-commit commit-hash))))

(defun blamer-callback-open-remote (commit-info)
  (interactive)
  (let ((commit-hash (plist-get commit-info :commit-hash)))
    (when commit-hash
      (message commit-hash)
      (forge-browse-commit commit-hash))))

(setq blamer-bindings '(("<mouse-3>" . blamer-callback-open-remote)
                        ("<mouse-1>" . blamer-callback-show-commit-diff)))

Also, you can use timemachine or select the commit in the magit log:

(defun blamer-callback-magit-log-file (commit-info)
  (interactive)
  (magit-log-buffer-file)
  (let ((commit-hash (plist-get commit-info :commit-hash)))
    (when commit-hash
      (run-with-idle-timer 1 nil (lambda (commit-hash)
                                   (goto-char (point-min))
                                   (search-forward (substring commit-hash 0 7))
                                   (set-mark (point-at-bol))
                                   (goto-char (point-at-eol)))
                           commit-hash))))

(defun blamer-callback-timemachine (commit-info)
  (interactive)
  (git-timemachine))

Contribute

Run before push

eldev prepare && eldev -p -dtT -C test

For more information check this repo

More images

Similar packages

• Sideline blame

Blamer.el plans [16/16]

• [X] Get necessary information about current line under cursor
• [X] Get commit info by current hash (if necessary)
• [X] Get background color if hl-mode is exist and enabled (transparency)
• [X] Visualize information in special format
• [X] blamer-mode implementation
• [X] Write tests for regexps
• [X] IDLE time before showing
• [X] Special font for blame.
• [X] Truncate long commit line
• [X] Add pretty date format
• [X] Pretty author name
• [X] Add support for common line number changed (might be deleted from external source, or evil keys)
• [X] Add support for global mode
• [X] Add support for multi line selection
• [X] Canonical blamer format + templates.
• [X] Clickable annotations