Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Artawower/blamer.el

A git blame plugin for emacs inspired by VS Code's GitLens plugin
https://github.com/Artawower/blamer.el

blamer emacs emacs-lisp git gitlens

Last synced: about 1 month ago
JSON representation

A git blame plugin for emacs inspired by VS Code's GitLens plugin

Lists

README 

        
#+TITLE: Blamer.el

#+html: 

[[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: 

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

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



* 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 '(("" . blamer-callback-open-remote)

                          ("" . 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]]



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