evil-commentary is an Emacs package for evil-mode that intends to make it easy to comment out (lines of) code:
- gcc comments out a line (takes a count)
- gc comments out the target of a motion, e.g. gcap to comment out a paragraph (normal state) and gc to comment out the selection (visual state).
This package is a port of the vim-commentary plugin for Vim. I wrote this because I really admire the work of tpope, its author, and wanted to have something really simple (less than 100 lines) like vim-commentary.
evil-commentary is considered feature complete as of v2.0.0,
though additional integrations may be added in the future.
The easiest way to install evil-commentary is to use package.el to
obtain it from Melpa:
M-x package-install RET evil-commentary RETYou can now try it with:
M-x evil-commentary-modeTo enable evil-commentary permanently, add
(evil-commentary-mode)to your init.el.
Alternatively, you can manually clone evil-commentary
to your load-path using something like this:
(add-to-list 'load-path "/path/to/evil-commentary")
(require 'evil-commentary)
(evil-commentary-mode)Here is an overview of the provided commands and their default key bindings:
| Map | Command |
|---|---|
| gc | evil-commentary |
| gy | evil-commentary-yank |
| s-/ | evil-commentary-line |
| evil-commentary-yank-line |
The default key bindings use gc
for the evil-commentary operator command.
That means it can be used with all available motions and counts,
just like other operator commands, such as evil-delete.
gcc comments out a line,
and 3gcc comments out three lines.
Try gcap to comment out a paragraph
or to uncomment a paragraph that is already commented out.
evil-commentary can also be used in the ex command line,
which is usually brought up by pressing :. As an example,
:g/TODO/evil-commentary
toggles comments on all lines that contain the string "TODO".
The default bindings also bind super+/
to evil-commentary-line, which comments out a single line,
since that is the de facto standard shortcut in many text editors.
It also works in emacs and insert states.
(Keep in mind that evil is still required.)
When editing code,
it is common to try different variations of a piece of code,
or to run a program with different settings.
This is where evil-commentary-yank
(and evil-commentary-yank-line) can be very helpful.
This command does the same as evil-commentary,
but also copies the original (uncommented) code
so that it can be easily pasted and modified afterwards.
By default, this functionality is bound to gy.
As an example, gyyp comments out a line of code (gyy)
and puts the original line of code after the current one (p).
By default, evil-commentary uses the comment-or-uncomment function.
It is possible to specify a different comment function by adding it
evil-commentary-comment-function-for-mode-alist, which is an
alist that maps a major mode (a symbol) to a comment function
(also a symbol).
A comment function must accept beg and end (both buffer positions)
as its required parameters. You can use the source code for the bundled
integrations as an example.
You can bind evil-commentary and evil-commentary-line to
other keys than the defaults. For example:
(define-key evil-motion-state-map "," nil)
(evil-define-key 'normal evil-commentary-mode-map
",c" 'evil-commentary)
(define-key evil-commentary-mode-map
(kbd "M-;") 'evil-commentary-line)If you think that ,cc is more convenient,
have a look at evil-space to keep evil-repeat-find-char functional.
❯ cask exec ecukes
Evil-Commentary mode enabled
.
Evil-Commentary mode enabled
.
2 scenarios (0 failed, 2 passed)
17 steps (0 failed, 0 skipped, 17 passed)