/blamer.el

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

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

Blamer.el

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

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

Preview

./images/preview.gif

Install

Emacs 27.1 is required.

Melpa

(use-package blamer
  :ensure t
  :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)
  :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
  :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.

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)

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

Contribute

Run before push

emacs -batch -l ert -l blamer.el -l test.el -f ert-run-tests-batch-and-exit

Blamer.el plans [15/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.
  • [ ] Clickable annotations