Blamer.el

#+TITLE: Blamer.el #+html: <img src="./images/evil-monkey.png" align="right" width="16%"> [[https://github.com/artawower/blamer.el/actions/workflows/lint.yml/badge.svg]] [[https://melpa.org/packages/blamer-badge.svg]] [[http://stable.melpa.org/packages/blamer-badge.svg]] [[https://wakatime.com/badge/user/dc4b055e-22c9-4977-bee4-51539164ae23/project/6da6ddac-b13a-47e2-8025-9fee277f2d3c.svg]] [[https://github.com/artawower/blamer.el/actions/workflows/melpazoid.yml/badge.svg][https://github.com/artawower/blamer.el/actions/workflows/melpazoid.yml/badge.svg]]

A git blame plugin for emacs inspired by [[https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens][VS Code's GitLens plugin]] and [[https://github.com/APZelos/blamer.nvim][Vim plugin]]

• Preview [[./images/preview.gif]]

• Install Emacs 27.1 is required. *** Melpa #+BEGIN_SRC emacs-lisp (use-package blamer :ensure t :bind (("s-i" . blamer-show-commit-info) ("C-c 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)) #+END_SRC

*** quelpa #+BEGIN_SRC emacs-lisp (use-package blamer :quelpa ((blamer :fetcher github :repo "artawower/blamer.el") :upgrade t) :bind (("s-i" . blamer-show-commit-info) ("C-c 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)) #+END_SRC *** Straight #+BEGIN_SRC emacs-lisp (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)) #+END_SRC

*** doom packages.el #+BEGIN_SRC emacs-lisp (package! blamer) ;; or (package! blamer :recipe (:host github :repo "artawower/blamer.el")) #+END_SRC

config.el #+BEGIN_SRC emacs-lisp (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)) #+END_SRC

• 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. #+html: <img src="./images/formatted.jpg" align="center" width="100%"> **** 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)

• ='margin-overlay= - show commit info in the margin

• ='posframe-popup= - posframe popup (see images/posframe.png)

• ='echo-area= - show commit info for the current line in the echo area.

  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: #+BEGIN_SRC emacs-lisp (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) #+END_SRC

**** 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.

**** Echo area /Echo area specific customizations/

~blamer-echo-area-inset~ - number of leading characters the remove when rendering in the echo area.

~blamer-echo-area-strip-face-attributes~ - list of face-attributes to remove when rendering in the echo area.

• 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):

#+BEGIN_SRC emacs-lisp (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))) #+END_SRC

Also, you can use [[https://github.com/emacsmirror/git-timemachine][timemachine]] or select the commit in the magit log: #+BEGIN_SRC emacs-lisp (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)) #+END_SRC

• Contribute Run before push #+BEGIN_SRC bash eldev prepare && eldev -p -dtT -C test #+END_SRC

For more information check [[https://github.com/doublep/eldev/][this]] repo

• More images [[./images/blamer-pretty-popup-dark.jpg]] [[./images/avatar-preview.png]] [[./images/posframe.png]]

• Similar packages

• [[https://github.com/emacs-sideline/sideline-blame][Sideline blame]]
• [[https://github.com/ISouthRain/emsg-blame][emsg-blame]]