branch: elpa/why-this
commit 9c0daa799c10fe3579f0d740ab1ab8cad7448437
Author: Akib Azmain Turja <a...@disroot.org>
Commit: Akib Azmain Turja <a...@disroot.org>
Rename a variable, change backend API and update docs
---
README.org | 23 +++++++++++++++++++++++
why-this.el | 49 +++++++++++++++++++++++++++++++++++--------------
2 files changed, 58 insertions(+), 14 deletions(-)
diff --git a/README.org b/README.org
index 9287efb7b6..9040d50b29 100644
--- a/README.org
+++ b/README.org
@@ -24,6 +24,13 @@ Editing history with heat map.
:repo "https://codeberg.org/akib/emacs-why-this.git";))
#+end_src
+* Supported version control systems
+
+Current only two version control systems are supported:
+
+- Git
+- Mercurial (Note: changes must be commited to be shown)
+
* Usage
Type =M-x why-this-mode= to enable showing blame.
@@ -41,6 +48,8 @@ possible buffer:
(global-why-this-mode)
#+end_src
+Note: ~why-this-mode~ won't be enabled on unsupported buffer.
+
Output by ~why-this-annotate~ may be hard to read depending on the theme.
Put the following in your init file to change the colors:
@@ -57,3 +66,17 @@ Put the following in your init file to change the colors:
(setq why-this-annotate-heat-map-cold "#dde3f4")
(setq why-this-annotate-heat-map-warm "#f0e0d4")
#+end_src
+
+To disable the heat map:
+
+#+begin_src emacs-lisp
+(setq why-this-annotate-enable-heat-map nil)
+#+end_src
+
+Hovering on the message shows a tooltip, to disable it:
+
+#+begin_src emacs-lisp
+(setq why-this-enable-tooltip nil)
+#+end_src
+
+To see all user options =M-x customize-group RET why-this=.
diff --git a/why-this.el b/why-this.el
index d5df6905bc..3c8da57a8f 100644
--- a/why-this.el
+++ b/why-this.el
@@ -44,7 +44,22 @@
(defcustom why-this-backends '(why-this-git
why-this-hg)
- "List of enabled backends."
+ "List of enabled backends.
+
+Each backend is a function taking variable number of arguments, where the
+first argument is the command (which is a symbol):
+
+`supported-p': Return whether the current buffer is supported.
+
+`line-data': Return a list of plist containing data about lines from BEGIN
+to END (exclusive), where BEGIN is the second argument and END is the third
+argument. Each plist describe BEGIN+Nth line, where N is the index of the
+plist in list. Plist contains the following properties:
+
+ `:id' Unique ID for each change (or commit).
+ `:author' Name of the author.
+ `:time' Time of change (local).
+ `:desc' Single line description of change."
:type '(repeat (function :tag "Backend"))
:package-version '(why-this "1.0")
:group 'why-this)
@@ -62,7 +77,11 @@ substituted by text describing the author, time or message:
`format-time-string').
%i Message.
-The value can also be a function to do the formatting itself."
+The value can also be a function to do the formatting itself. The function
+should take a plist as the first and only argument. The plist is same as
+the plists returned by backends when `line-data' command is given (see
+`why-this-backends'), with an additional property `:backend' whose value is
+is the backend which generated the plist."
:type '(choice (string :tag "Format string")
(function :tag "Formatter function"))
:package-version '(why-this "1.0")
@@ -100,8 +119,8 @@ NICK."
:package-version '(why-this "1.0")
:group 'why-this)
-(defcustom why-this-annotate-length 70
- "Length of annotation done by `why-this-annotate'."
+(defcustom why-this-annotate-width 70
+ "Width of annotation done by `why-this-annotate'."
:type 'integer
:package-version '(why-this "1.0")
:group 'why-this)
@@ -222,7 +241,7 @@ When EXACT is non-nil, be as exact as possible."
(?T . (format-time-string "%d %B %Y"
(plist-get data :time)))
(?t . (why-this-relative-time (plist-get data :time)))
- (?i . (plist-get data :message)))))
+ (?i . (plist-get data :desc)))))
(replace-regexp-in-string
"%."
(lambda (str)
@@ -463,7 +482,7 @@ Actually the supported backend is returned."
(equal (plist-get line :id)
(plist-get (nth (1- i) data) :id)))
(insert
- (format (format "%%%is" why-this-annotate-length) "")
+ (format (format "%%%is" why-this-annotate-width) "")
why-this-annotate-separator
(format (format "%%%ii" (length (number-to-string
line-count)))
@@ -487,12 +506,12 @@ Actually the supported backend is returned."
(format "%%-%is"
why-this-annotate-author-length)
(plist-get line :author)))
- (message-length (- why-this-annotate-length
+ (message-length (- why-this-annotate-width
why-this-annotate-author-length
(length time) 4))
(message (format
(format "%%-%is" message-length)
- (plist-get line :message))))
+ (plist-get line :desc))))
(why-this--insert-and-truncate
author why-this-annotate-author-length)
(insert " ")
@@ -588,7 +607,7 @@ Do CMD with ARGS."
:id uncommitted-commit-hash
:author why-this--git-author-name
:time (current-time)
- :message "Uncommitted changes")))))))
+ :desc "Uncommitted changes")))))))
(delete-file temp-file)
(setq blame (butlast blame))
(when (zerop status)
@@ -623,7 +642,7 @@ Do CMD with ARGS."
:time (time-convert
(string-to-number
(cdr (assoc-string "author-time" data))))
- :message (cdr (assoc-string "summary" data)))))))
+ :desc (cdr (assoc-string "summary" data)))))))
(setq i (1+ i))))))
(while (< (length line-data) (- (nth 1 args) (nth 0 args)))
(funcall add-uncommitted))
@@ -649,7 +668,7 @@ Do CMD with ARGS."
(concat
"hg annotate \"%s\" --template \"({lines %% '(:id"
" {rev} :author \\\"{person(user)}\\\" :time"
- " ({hgdate(date)}) :message \\\"{sub(\\\"\\\\\\\"\\\","
+ " ({hgdate(date)}) :desc \\\"{sub(\\\"\\\\\\\"\\\","
" \\\"\\\\\\\\\\\\\\\"\\\", sub(\\\"\\n.*\\\","
" \\\"\\\", desc))}\\\") '})\"")
(buffer-file-name))))))
@@ -657,8 +676,10 @@ Do CMD with ARGS."
(dolist (i (number-sequence (1- (nth 1 args)) (nth 0 args) -1))
(if (<= i (length output))
(let ((plist (nth (1- i) output)))
- (plist-put plist :time (time-convert
- (car (plist-get plist :time))))
+ (setq plist
+ (plist-put plist :time
+ (time-convert
+ (car (plist-get plist :time)))))
(push plist data))
(setq data
(append data
@@ -667,7 +688,7 @@ Do CMD with ARGS."
:id nil
:author user-full-name
:time (current-time)
- :message "Uncommitted changes"))))))
+ :desc "Uncommitted changes"))))))
data)))))
(provide 'why-this)
