README

More friendly interface for ivy

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

A transformer is just a string processing function with some format properties. The transformer format for each ivy command is defined in the 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 this for an example.

Convenience functions

Convenience functions exist for customizing column properties without rewriting the entire transformer definition

ivy-rich-modify-column: Update properties of existed transformer column.
ivy-rich-modify-columns: Like ivy-rich-modify-column, but for multiple columns.
ivy-rich-set-columns: Set/Replace transformer columns.

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.

Important Changes

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.

FAQ

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`?

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

Related Packages

ivy-filthy-rich.el by @casouri
all-the-icons-ivy by @asok
all-the-icons-ivy-rich by @seagle0128

Yevgnen/ivy-rich