guide.adoc

10 steps to become evil

Before getting started..

• I don’t recommend iTerm because it’s a bit slow. I’m using Kitty terminal.

• Make sure to enable true color support in your terminal, or your Emacs would look bad.

  Still Emacs might not show accurate colors though!

• If you use tmux, set something like set-option -t 0 escape-time 20 for faster cursor movement.

• I recommend adjusting the key repeat speed of your OS (for faster cursor movement).

66 commits in 10 steps

1. Getting started

Install the latest version of Emacs. Configuration files are located at ~/.emacs.d:

$ mkdir ~/.emacs.d
$ cd ~/.emacs.d
$ : > init.el

Also, I made an alias em='emacs -nw', which starts Emacs in terminal.

If you try Doom Emacs or Spacemacs alongside your ~/.emacs.d, try chemacs, as the Doom Emacs doc says.

Initial commits

After the first four commits, I got ready to start emacs:

• I split my init.el into three files: evil.el, ide.el and keymap.el.

• I didn’t want Emacs to make backup files (where edited files are).

• I made sure to use UTF-8.

2. Become Evil

I became Evil:

• 3d646f0: set up use-package

• ce8f3c1: add Evil anyways

I wanted to be comfortable to edit init.el on Emacs:

• 0a1a913: use C-z for SIGTSTP

  Press Control + z (C-z) to make Emacs a background process and make commits with git! Run fg to come back to Emacs. Later I’ll add magit to use git in Emacs. I’m not yet familar with it though.

• 91f2913: set color scheme

  Choose colors of your choice! I’m using darkokai this time:

  

  More configurations coming soon..

• 1e4df40: format ELisp automatially

  Please! Also, now press zm to fold all and zr to open all. Press za to toggle. This is thanks to hs-minor-mode (hide-show minor mode).

  Considering folds, my ELisp files use this style of headers: ----…​ Header title …​---.

• a717f2b: add ex commands

  I use :ed to open init.el, :s to source (load) it. Mistake: the evil-split-buffer is actually evil-window-split. Sorry!

• 8a26cf8: enable undo with Evil

  Enable C-r (<C-r> in Vim’s notation) using undo-tree. You can use other backends, too.

• 1b4a7fc: open only one window on startup

  If we start emacs with multiple arguments (files), they’ll be opened in split windows, or a filer starts. I fixed it to start with only one window like Vim. Different from Vim, Emacs opens the last file of arguments; if we run emacs -nw a b c, Emacs opens c (while Vim opens a). Let me know if you can change Emacs to open a in this case.

3. More like Evil

We’re not ready to use Emacs like Vim!

• d037aeb: configure Evil

  Evil tries not to overwrite Emacs defaults, but I’d rather want Vim-like settings.

• cefc6ec: practical Vim

  Surround and expand region like done in Practical Vim!

• fa4ed5f: add which-key

  Show keys after prefix automatically (this is C-w):

  

  Also, show keys in a major mode with C-h M!

• f69f4b3: show help with K

  coc.nvim recommends showing hints on cursor with K. I wanted to do something similar with helpful.

  Other option would be Popup Help In Emacs Lisp. That’s awesome but I wasn’t able to show helpful help with popup.el, so I ended up with this commit.

• ed67456: hide more and show more

  Please!

• 72f1ed4: input support for terminal

  I don’t know how to use the + register (clipboard) on terminal (evil#380). OMG. I added :copy command to copy to clipboard with clipetty. But then it’s a bit verbose to do domething like "+dd". Also clipetty can’t copy long text on Kitty terminal at least for now. So my terminal support is not a 100% thing.

• 6329ad4: scroll like Vim

  Please!

4. Emacs is our yard

Now we need better looks and some utilities!

• 7eb498a: add git-gutter

  Show diffs on the line numbers! Use fringe version of it in GUI.

  

• f135123: add more highlights

  Rainbow parentheses and TODO highlight!

• c6c252e: enable builtin packages

  • recentf: remember recently opened files.

  • savehist-mode: save command history.

  • save-place-mode: remember cursor positions per file.

  • auto-revert-mode: sync buffers to storage (when an external program modifies them).

  • uniquify: diffentinate duplicate file names (as file-name<dir>).

    Auto-generated files by the packages will be put in ~/.emacs.d/tmp.

• 5066f0e: add hack to re-center cursor position for save-place-mode

  save-place-mode places our cursor at the bottom of the window. I don’t want to look for the cursor and press zz everytime I open a file, so this hack is helpful.

• 03346f1: add dashboard

  It’s good for selecting a project when we start Emacs from GUI. Later I’ll polish a bit.

• aed80fc: add doom-modeline

  doom-modeline is a better version of bottom bar.

5. Even eviler

Some details for Vimmers..

• 0aead19: be Evil everywhere

  I didn’t like Evil/Emacs context switching (when entering *Messages* etc.).

• a7fff79: add evil-escape

  Press jk or kj to quit.

• a0ab641: EVIL

  Add more essential Evil settings.

• 38b3e2f: add Evil policies

  Map x to "_x, n to nzz, etc. I forgot to add this function, sorry:

  (defun toy/force-center()
      (evil-scroll-line-to-center (line-number-at-pos)))

6. Key mappings

Some mappings are on my taste, others are useful to other Vimmers, too.

• 6a3f095: add Emacs-like key mappings

  I’m on mac so this is natural; those mappings are available in almost any other app on mac.

• 3c68461: add misc key mappings

  SPC /: toggle comment, C-s: return to normal mode and save.

• 50e0fb3: add [] mappings

  Like unimpaired.vim.

• 9b63723: skip ^* buffers with ]b and [b

  I wanted to not cycle through buffers such as *Messages* or *Warnings* with ]b or [b. Just skip them all! When we need, we can visit those files with a fuzzy finder (added later).

• 551a61f: add centaur-tabs

  It makes groups of buffers and shows them on windows. Super nice. To me, it’s one of the killer features of Emacs.

• 031554f: use ]w and [w to cycle through windows

  I love this.

• 24bac64: add evil packages

  That is, evil-string-inflection and evil-lion. I use evil-lion’s motions to align tables in AsciiDoc files.

  Later I’ll add evil-matchit (they fixed my bug report in one day!).

7. Even rich (fuzzy finder support)

Emacs is…​ nice :D

• b389aaa: add company (COMP-lete ANY-thing)

  Now even ELisp is easier to edit! There are too many things that deserve "the first thing to do". Also I made sure we can use C-n and C-p to cycle through completion items.

• 81ca75f: add Ivy and Projectile

  Ivy is our fuzzy finder. Key mappings will be added later. I also added ivy-rich, which makes Ivy, well, rich (e.g. show both item and description). Don’t miss it! Projectile is the de-fact project manager of Emacs. Even if we don’t directly call their methods, some packages do, so we need it.

• 5772dcb: add keys to Ivy mapping

  I don’t use meta key and super key so I added some control+key mappings. Press C-l to preview, C-k to kill. Press C-, to open menu. C-f and C-b are also useful. Later we’ll add hydra, then press C-o to open ivy-hydra.

• 4021588: add counsel

  counsel is a set of fuzzy finding functions. I mapped i_CTRL-r to one in the package.

• 13dac18: add all-the-icons

  For GUI.

• 7986330: add counsel mappings

  Now, the fuzzy finder is in our hands!

  

• bcb67cd: translate ESC and C-c to C-g in non-Evil mode

  This is useful in Ivy minibuffers (spawned by a counsel function). Other option would be using evil-collection.

• b7ce0fc: add swiper

  swiper is "an Ivy-enhanced alternative to isearch". I mapped * to search with swiper. Also I added SPC gb for grep this buffer and SPC gB for grep all buffers.

• 5dbd1d2: update packages every 7 day

  I should have done it earlier.

• 07814b4: put projectile cache files in tmp/ directory

  Plz

• 0de195a: add neotree

  

  neotree is an alternative to NERDTree in Vim. neotree is easy to use, but treemacs supports multiple root directories, so I’d try treemacs later (though it won’t be included in this repo).

• 8e856f1: add keys to neotree-mode-map

  Settings on my taste, maybe similar to NERDTree defaults.

• 376bdbe: add neotree keys

  Setings on my taste.

Now our Emacs is intelligent enough! Language server supports will be added later.

8. Emacs is our home

Make Emacs a default editor for us!

• 2eca493: add GC configuration

  1.5x faster startup time (acoording to emacs-init-time)!

• daa2fe1: add early-init.el

  Even faster startup!

• 691511c: add olivetti and zoom-window

  olivetti is a per-buffer distraction-free writing mode. Awesome! The drawback is that our gj and gk don’t make sense in that mode. zoom-window is for maximizing one window.

  Alternatives to olivetti would be darkroom and writeroom-mode.

• fd63099: highlight DSLs

  Including markup languages.

• 7a4b5ea: add magit

  Start magit in other window or the full frame (with olivetti, which alignes magit to the center of the frame).

• d9d928d: oooh fix :hs

  Fix to an earlier commit.

• c10c23e: add hydra and toy/hydra-window

  Mistake: please refer to the latest file. Now, press SPC w to enter window mode created with hydra!

• 00e47b5: fix path of .last-package-update-day

  Fix to an earlier commit.

• 6673c31: add toy/reset

  Press SPC SPC SPC x to kill almost all buffers and come back to the dashboard.

• e6b2a39: polish init.el

  Just some refactoring.

• cc99d41: add missing toy/force-center

  Fix to earlier commits.

• a115b4d: put magit files in tmp/

  traisient is now in tmp!

• 1819869: add details

  I needed these small utilities.

9. Emacs is an Intelligent Development Environment

After coming to this place, it’s a peace of cake.

• ef996ee: set up PATH and exec-path

  LSP servers are found from PATH so this is an important setting.

• f218bbd: add evil-matchit

  Not related to LSP. They fixed my bug report in one day so I added it!

• d0a8754: add lsp-mode and rustic

  Please refer to the lsp-mode documentaions below to make sure your lsp-mode runs fast enough!

  Now we can edit Rust programs with LSP supports. Seems like it’s not perfect, e.g., when I use include_file! in my sys crate.. but looks good overall!

• c423c4c: add lsp-treemacs

LSP mode

I’m not quiet sure about lsp-mode configuration. Please refer to their awesome websites:

• lsp-mode

  • Performance

  • A guide on disabling/enabling lsp-mode features

• lsp-ui

10. TODOs

• More comfortable key mappings, especially in LSP error lists (flycheck and treemacs).

• The Evil/Emacs context switching is not perfect. I need more fix.

• In-editor terminal support. Maybe in a floating terminal (is it possible in terminal?) or a VSCode-like terminal pane.

• GUI support (awesome posframe etc.).

• Workspace support: builtin tab mode, elscreen, persp-mode, eyebrowse and more. I’d look into them.. when I have time.

Done!

Thank you for reading.. if anyone is there :)

I used to not like every details of Evil Emacs, but now, I’m thinking the opposite. Still, some features like clipboard don’t work well on terminal, so I need more polishing.

Notes

emacs-init-time says it took 1.07 seconds to start my emacs with my Rust files, but it’s actually 3x longer (maybe to set up LSP). For plain text files, my emacs -nw is fast enough.

I didn’t use after-init-hook because I didn’t think it made sense. after-init-hook is run after emacs-init-time, so after-init-hook pretends faster startup, which is obviously not a good thing. Just my curious, but is there any pros? If so, I’d like to make changes.

I didn’t use evil-collection because I was not sure what it was doing.

I didn’t consider using byte compilation. Because it didn’t contribute to even 0.01 sec of time. Also, I don’t know how to use use-package when we split our init.el; I couldn’t call use-package in a file where use-package is not boostrapped.

What’s next

• We didn’t get key mappnings to open/goto a file in other window. I’d figure out how to do it.

• We can’t easily fork packages. We can switch from package.el to straight.el.

• leaf.el should be a better version of use-package (though I don’t have a plan to give it a try).

• Now which-key is not showing beautiful tips (some are lambda, which is no information). We can use general.el to set both key bindings and which-key comments at the same time.

• We don’t have multi-root directory supports in the sidebar. treemacs does.

• I didn’t look into emacs-tree-sitter, which provides better code highlighting.

References

• Evil - Documentation

• evil-guide

Thanks!