This package comes with rich transformers for commands from ~ivy~ and ~counsel~. It should be easy enough to define your own transformers too.
Screenshots are available [[file:screenshots.org][here]].
** Installation
~M-x package-install RET ivy-rich RET~
** Basic Usages
(require 'ivy-rich) (ivy-rich-mode 1)
It is recommended to set also
(setcdr (assq t ivy-format-functions-alist) #'ivy-format-function-line)
** Customization :PROPERTIES: :CUSTOM_ID: h:6A171A3A-50DF-42F6-B19B-321B160F198E :END:
A transformer is just a string processing function with some format properties. The transformer format for each ~ivy~ command is defined in the [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Property-Lists.html#Property-Lists][plist]] ~ivy-rich-display-transformers-list~. 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.
You can also define your own transformers, see [[id:20201229-how-i-can-add-icons-for-ivy-switch-buffer][this]] for an example.
** Convenience functions
Convenience functions exist for customizing column properties without rewriting the entire transformer definition
Below are two examples 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:
(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:
(ivy-rich-modify-columns 'ivy-switch-buffer '((ivy-rich-switch-buffer-size (:align right)) (ivy-rich-switch-buffer-major-mode (:width 20 :face error))))
Refer to the docstring for more details.
** Additional settings for ~ivy-switch-buffer~
To abbreviate paths using ~abbreviate-file-name~ (e.g. replace "/home/username" with "~")
(setq ivy-rich-path-style 'abbrev)
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=.
Note that this may not affect remote files. 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~.
*** Project Performance
When having many open buffers, calling and navigating ~ivy-switch-buffers~ might become slow when you have project-related columns. If that's the case, you can enable ~ivy-rich-project-root-cache-mode~, to cache each buffers project. The project for a buffer is cached until the buffer is killed, ~ivy-rich-project-root-cache-mode~ is disabled or ~ivy-rich-clear-project-root-cache~ is called.
** Notes
If you modify ~ivy-rich-display-transformers-list~, you may need to disable and re-enable ~ivy-rich-mode~ again to make the changes take effect.
If you define transformers for commands comes from neither ~ivy~ nor ~counsel~, e.g. ~counsel-projectile-*~, it currently may not take effect since if you enable ~ivy-rich-mode~ before loading ~counsel-projectile~, the transformer setting is overwritten by loading the package. Try to load all these packages before loading ~ivy-rich~.
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 for ~ivy-switch-buffer~ is ~ivy-switch-buffer-transformer~ from the ~ivy~ package. But if you set the transformer to ~some-function~ before enabling ~ivy-rich-mode~, disabling the minor mode will restore it to ~some-function~ other than ~ivy-switch-buffer-transformer~.
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 [[#h:6A171A3A-50DF-42F6-B19B-321B160F198E][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~ in ~ivy-switch-buffer~?
No, as far as I know, you can not right now. ~ivy-rich~ provides just transformers to display the original ~ivy~ 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 in ~ivy~.
So you can not search the description of ~counsel-describe-function~ neither.
** How I can add icons for ~ivy-switch-buffer~? :PROPERTIES: :ID: 20201229-how-i-can-add-icons-for-ivy-switch-buffer :END:
The package [[https://github.com/domtronn/all-the-icons.el][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 plist value of ~ivy-switch-buffer~ in ~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)))))
See also [[https://github.com/seagle0128/all-the-icons-ivy-rich][all-the-icons-ivy-rich]].
Related Packages
[[https://github.com/casouri/ivy-filthy-rich][ivy-filthy-rich.el]] by @casouri
[[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]] by @asok
[[https://github.com/seagle0128/all-the-icons-ivy-rich][all-the-icons-ivy-rich]] by @seagle0128