The package current comes with support for ivy-switch-buffer
,
counsel-M-x
, counsel-describe-function
and counsel-describe-variable
,
but it should be easy enough to define your own
transformers. Screenshots are available here.
package-install RET ivy-rich RET
(require 'ivy-rich)
(ivy-rich-mode 1)
It is recommended to set also
(setcdr (assq t ivy-format-functions-alist) #'ivy-format-function-line)
The transformer format for each ivy
command is defined in plist
ivy-rich-display-transformers-list
, which has a default value
'(ivy-switch-buffer
(:columns
((ivy-switch-buffer-transformer (:width 30)) ; add face by the original transformer
(ivy-rich-switch-buffer-size (:width 7)) ; return buffer size
(ivy-rich-switch-buffer-indicators (:width 4 :face error :align right)) ; return buffer indicator
(ivy-rich-switch-buffer-major-mode (:width 12 :face warning)) ; return major mode info
(ivy-rich-switch-buffer-project (:width 15 :face success)) ; return project name `projectile'
(ivy-rich-switch-buffer-path (:width (lambda (x) (ivy-rich-switch-buffer-shorten-path x (ivy-rich-minibuffer-width 0.3)))))) ; return file path relative to project root or `default-directory' if project is nil
:predicate
(lambda (cand) (get-buffer cand)))
counsel-find-file
(:columns
((ivy-read-file-transformer)
(ivy-rich-counsel-find-file-truename (:face font-lock-doc-face))))
counsel-M-x
(:columns
((counsel-M-x-transformer (:width 40))
(ivy-rich-counsel-function-docstring (:face font-lock-doc-face)))) ; return docstring of the command
counsel-describe-function
(:columns
((counsel-describe-function-transformer (:width 40))
(ivy-rich-counsel-function-docstring (:face font-lock-doc-face)))) ; return docstring of the function
counsel-describe-variable
(:columns
((counsel-describe-variable-transformer (:width 40))
(ivy-rich-counsel-variable-docstring (:face font-lock-doc-face)))) ; return docstring of the variable
counsel-recentf
(:columns
((ivy-rich-candidate (:width 0.8))
(ivy-rich-file-last-modified-time (:face font-lock-comment-face)))) ; return last modified time of the file
package-install
(:columns
((ivy-rich-candidate (:width 30))
(ivy-rich-package-version (:width 16 :face font-lock-comment-face)) ; return package version
(ivy-rich-package-archive-summary (:width 7 :face font-lock-builtin-face)) ; return archive summary
(ivy-rich-package-install-summary (:face font-lock-doc-face))))) ; return package description
A transformer is just a string processing function with some format
properties. Each plist key is a ivy
command and plist value is its
transformer format definitions or a pre-defined transformer. Refer to
the documentation of ivy-rich-display-transformers-list
for details.
Convenience functions exist for customizing column properties without
rewriting the entire transformer definition. Below are two examples with
use-package
that use the default transformers, but with user-defined
customizations.
This example customizes the :width
and :face
properties of the major
mode column in the ivy-switch-buffer
transformer:
(use-package ivy-rich
:config
(ivy-rich-modify-column 'ivy-switch-buffer
'ivy-rich-switch-buffer-major-mode
'(:width 20 :face error)))
This example customizes properties of two columns of the ivy-switch-buffer
transformer and shows some other configuration options via use-package
:
(use-package ivy-rich
:hook (ivy-mode . ivy-rich-mode)
:custom (ivy-rich-path-style 'abbrev)
:config
(ivy-rich-modify-columns
'ivy-switch-buffer
'((ivy-rich-switch-buffer-size (:align right))
(ivy-rich-switch-buffer-major-mode (:width 20 :face error)))))
For example, the transformer for counsel-M-x
counsel-M-x
(:columns
((counsel-M-x-transformer (:width 40))
(ivy-rich-counsel-function-docstring (:face font-lock-doc-face))))
it defines two columns. The first one is the original built-in
transformer with max width of 40 chars and the second one transforms the
string candidate into a docstring with face font-lock-doc-face
.
The package all-the-icons.el provides functionality to use icon fonts easily in emacs. For example, you can define a transformer
(defun ivy-rich-switch-buffer-icon (candidate)
(with-current-buffer
(get-buffer candidate)
(let ((icon (all-the-icons-icon-for-mode major-mode)))
(if (symbolp icon)
(all-the-icons-icon-for-mode 'fundamental-mode)
icon))))
and add it to the ivy-rich-display-transformers-list
(setq ivy-rich-display-transformers-list
'(ivy-switch-buffer
(:columns
((ivy-rich-switch-buffer-icon (:width 2))
(ivy-rich-candidate (:width 30))
(ivy-rich-switch-buffer-size (:width 7))
(ivy-rich-switch-buffer-indicators (:width 4 :face error :align right))
(ivy-rich-switch-buffer-major-mode (:width 12 :face warning))
(ivy-rich-switch-buffer-project (:width 15 :face success))
(ivy-rich-switch-buffer-path (:width (lambda (x) (ivy-rich-switch-buffer-shorten-path x (ivy-rich-minibuffer-width 0.3))))))
:predicate
(lambda (cand) (get-buffer cand)))))
You will get
- If you modify
ivy-rich-display-transformers-list
, you may need to disable and re-enableivy-rich-mode
again to make the changes take effect. - If you define transformers for commands comes from neither
ivy
norcounsel
, e.g.counsel-projectile-*
, it currently may not take effect since if you enableivy-rich-mode
before loadingcounsel-projectile
, the transformer setting is overwritten by loading the package. I am considering to add a:package
keyword in the transformer definition to deal with this. - Disabling the minor mode
ivy-rich-mode
will restore the transformers to what they were before, but not necessarily to the ‘built-in default’ one. For example, the default transformer forivy-switch-buffer
isivy-switch-buffer-transformer
from theivy
package. But if you set the transformer tosome-function
before enablingivy-rich-mode
, disabling the minor mode will restore it tosome-function
other thanivy-switch-buffer-transformer
.
To abbreviate paths using abbreviate-file-name
(e.g. replace
“/home/username” with “~”)
(setq ivy-rich-path-style 'abbrev)
Note that this may not affect remote files. To always show absolute
path, set it to =’full= or =’absolute=. Any other value will show the file
path relative to the project root or default-Directory
.
There are two variables ivy-rich-parse-remote-buffer
and
ivy-rich-parse-remote-file-path
controls how remote buffers are
processed, please refer to the docstring of them for more details if you
have trouble using this function under tramp
.
Since the version 0.1.0 of ivy-rich
, the transformer format can be
customized. Variables from older version like
ivy-rich-switch-buffer-mode-max-length
or
ivy-rich-switch-buffer-project-max-length
has been deprecated since they
are now packed into ivy-rich-display-transformers-list
as stated in the
customization section.
Supports for virtual buffers and shorten file paths in ivy-switch-buffer
are temporarily Removed.
- Can I search buffers by
major-mode
,project
inivy-switch-buffer
?No, as far as I know, you can not right now.
ivy-rich
provides just transformers to display the originalivy
candidates in a different way. It does not modify the original candidates. At least for now I have no idea how to add feature to search in the transformer columns. It probably requires some change inivy
.
So you can not search the description of counsel-describe-function
neither.
- ivy-filthy-rich.el by @casouri
- all-the-icons-ivy by @asok
- all-the-icons-ivy-rich by @seagle0128