About

An Emacs library that extends the functionality of the ivy and counsel packages by providing extra utilities and commands.

Table of Contents

• About
• Requirements
• Installation
  • With use-package and straight.el
  • Manual installation
• Usage
  • Extended commands
  • File commands
  • Imenu commands
  • Describe commands
  • Bookmark commands
  • Misc commands
• Customization

Requirements

Name	Version
Emacs	28.1
ivy	0.14.0
counsel	0.14.0

Installation

The package requires Emacs 28.1 or later, as well as the ivy and counsel packages (version 0.14.0 or later).

With use-package and straight.el

(use-package counsel-extra
  :straight (:repo "KarimAziev/counsel-extra"
                   :type git
                   :host github)
  :hook ((ivy-mode . counsel-extra-add-extra-actions)
         (counsel-mode . counsel-extra-configure-find-file))
  :bind ((:map counsel-extra-M-x-keymap
               ("C-c o" . counsel-extra-M-X-find-symbol-in-other-window-cmd))
         (:map counsel-extra-bookmark-map
               ("C-c o" . counsel-extra-bookmark-in-other-window))))

Full example of configuration

(use-package counsel-extra
  :after counsel
  :demand t
  :straight (:repo "KarimAziev/counsel-extra"
             :type git
             :host github)
  :bind (("C-x C-c" . counsel-extra-color-menu)
         (:map counsel-extra-M-x-keymap
          ("C-c o" . counsel-extra-M-X-find-symbol-in-other-window-cmd))
         (:map counsel-extra-bookmark-map
          ("C-c o" . counsel-extra-bookmark-in-other-window))
         (:map ivy-minibuffer-map
          :package ivy
          ("C-c TAB" . counsel-extra-ivy-insert)
          ("C-SPC" . counsel-extra-ivy-mark)
          ("M-w" . counsel-extra-ivy-copy)
          ("C-c g g" . counsel-extra-ivy-browse-url))
         (:map ivy-switch-buffer-map
          :package ivy
          ("C-c TAB" . counsel-extra-ivy-insert)
          ("C-c o" . counsel-extra-switch-to-buffer-other-window))
         (:map counsel-mode-map
          :package counsel
          ("C-c g s" . counsel-extra-search)
          ("C-x P" . counsel-extra-list-processes)
          ([remap execute-extended-command] . counsel-extra-M-x))
         (:map counsel-find-file-map
          :package counsel
          ("C-j" . counsel-extra-expand-dir-maybe)
          ("RET" . counsel-extra-expand-dir-done)
          ("M-D" . counsel-extra-delete-file)
          ("C-c M-w" . counsel-extra-copy-file)
          ("C-c M-r" . counsel-extra-move-file)
          ("C-c o" . counsel-extra-open-file-other-window)
          ("C-x d" . counsel-extra-dired))
         (:map counsel-imenu-map
          :package counsel
          ("C-c TAB" . counsel-extra-imenu-insert-cmd)
          ("C-c o" . counsel-extra-imenu-jump-to-item-in-other-window))
         (:map counsel-describe-map
          :package counsel
          ("C-c o" . counsel-extra-find-symbol-in-other-window)))
  :config
  (setq-default counsel-extra-align-M-x-description 50
                counsel-extra-show-modified-time t)
  (when (fboundp 'counsel-extra-add-extra-actions)
    (counsel-extra-add-extra-actions))
  (when (fboundp 'counsel-extra-configure-find-file)
    (counsel-extra-configure-find-file)))

Manual installation

Download the source code and put it wherever you like, e.g. into ~/.emacs.d/counsel-extra/

git clone https://github.com/KarimAziev/counsel-extra.git ~/.emacs.d/counsel-extra/

Add the downloaded directory to the load path:

(add-to-list 'load-path "~/.emacs.d/counsel-extra/")
(require 'counsel-extra)

Usage

Extended commands

These commands are expected to be bound in the counsel-mode-map.

Show example

(require 'counsel)
(require 'counsel-extra)

(define-key counsel-mode-map (kbd "C-x P") 'counsel-extra-list-processes)
(define-key counsel-mode-map (vector 'remap 'execute-extended-command) 'counsel-extra-M-x)
(define-key counsel-mode-map (kbd "C-x c c") 'counsel-extra-colors-emacs)

• counsel-extra-M-x - Extra version of execute-extended-command.
• counsel-extra-list-processes - Offer completion for process-list. The default action is to switch to the process buffer. An extra action allows to delete the selected process.
• counsel-extra-colors-emacs - Show a list of all supported colors for a particular frame. Unlike `counsel-colors-emacs’ it is allows to define extra commands in it’s keymap - `counsel-extra-emacs-colors-map’.

File commands

These commands are expected to be bound in the counsel-find-file-map.

Show example

;; use-package example
(use-package counsel-extra
  :straight (:repo "KarimAziev/counsel-extra"
             :type git
             :host github)
  :bind ((:map counsel-find-file-map
          :package counsel
          ("C-j" . counsel-extra-expand-dir-maybe)
          ("RET" . counsel-extra-expand-dir-done)
          ("M-D" . counsel-extra-delete-file)
          ("C-c M-w" . counsel-extra-copy-file)
          ("C-c M-r" . counsel-extra-move-file)
          ("C-c o" . counsel-extra-open-file-other-window)
          ("C-x d" . counsel-extra-dired))))
;; or without use-package
(define-key counsel-find-file-map (kbd "C-j") 'counsel-extra-expand-dir-maybe)
(define-key counsel-find-file-map (kbd "RET") 'counsel-extra-expand-dir-done)
(define-key counsel-find-file-map (kbd "M-D") 'counsel-extra-delete-file)
(define-key counsel-find-file-map (kbd "C-c M-w") 'counsel-extra-copy-file)
(define-key counsel-find-file-map (kbd "C-c M-m") 'counsel-extra-move-file)
(define-key counsel-find-file-map (kbd "C-c o") 'counsel-extra-open-file-other-window)
(define-key counsel-find-file-map (kbd "C-x d") 'counsel-extra-dired)

• M-x counsel-extra-open-file-other-window - Quit the minibuffer and call find-file-other-window action.
• M-x counsel-extra-move-file - Quit the minibuffer and call counsel-find-file-move action.
• M-x counsel-extra-delete-file - Quit the minibuffer and call counsel-find-file-delete action.
• M-x counsel-extra-copy-file - Quit the minibuffer and call counsel-find-file-copy action.
• M-x counsel-extra-dired - Open file in Dired.
• M-x counsel-extra-expand-dir-done - Visit or preview currently selected directory or file. If it is a valid directory, visit it and stay in minibuffer, otervise

execute default ivy action and exit minibuffer.

• M-x counsel-extra-expand-dir-maybe - Visit or preview currently selected directory or file and stay in minibuffer. If it is not a valid directory, preview the file.

Imenu commands

These commands are expected to be bound in the counsel-imenu-map.

Show example

(define-key counsel-imenu-map (kbd "C-c o") 'counsel-extra-imenu-jump-to-item-in-other-window)
(define-key counsel-imenu-map (kbd "C-c TAB") 'counsel-extra-imenu-insert-cmd)

• M-x counsel-extra-imenu-insert-cmd - Quit the minibuffer and insert imenu item.
• M-x counsel-extra-imenu-jump-to-item-in-other-window - Jump to imenu item in other window

Describe commands

This command is supposed to be bound to counsel-describe-map.

Show example

(define-key counsel-describe-map (kbd "C-c o") 'counsel-extra-find-symbol-in-other-window)

• M-x counsel-extra-find-symbol-in-other-window - find symbol in other window and exit minibuffer.

Bookmark commands

• M-x counsel-extra-bookmark - Forward to bookmark-jump or bookmark-set if the bookmark doesn’t exist.
• M-x counsel-extra-bookmark-in-other-window - Open bookmark in another window.

Misc commands

These commands are expected to be bound in the ivy-minibuffer-map.

Show example

(define-key ivy-minibuffer-map (kbd "C-c C-p") 'counsel-extra-pp-ivy)
(define-key ivy-minibuffer-map (kbd "C-c C-i") 'counsel-extra-ivy-insert)
(define-key ivy-minibuffer-map (kbd "C-SPC") 'counsel-extra-ivy-mark)
(define-key ivy-minibuffer-map (kbd "C-c g g") 'counsel-extra-ivy-browse-url)
(define-key ivy-minibuffer-map (kbd "M-w") 'counsel-extra-ivy-copy)

Customization

counsel-extra-align-M-x-description

Whether to align command descriptions. If nil, don’t align, if integer align to those column.

counsel-extra-M-X-predicates

Command filtering predicates for counsel-extra-M-x command, that can be switched dynamically with M-X.

counsel-extra-show-modified-time

Whether to show file modified time in human readable format when reading filename.

counsel-extra-align-modified-time

Whether to align modified time when reading filename. This option has effect only if counsel-extra-show-modified-time is enabled.