I was skimming through the latest 2023 Rust Survey, and I noticed the 5th most popular “editor or IDE setup” is Helix. (Just ahead of emacs, even!) What the heck is Helix?
Helix seems to be:
- Rust IDE, seems to do other languages, too, but I’m interested in Rust.
- Heavily inspired by vim,
- Written in Rust
- Terminal-based (run remotely on some distant or headless target machine)
- Open source
This post? It started as my own cheat sheet, and I decided it might be useful to others. The goal is to tell you the very basics, enough to use Helix, not enough to get good at it. (I’m not.)
Installation
I decided to build it myself, they said:
$ git clone https://github.com/helix-editor/helix
[…]
$ cd helix/
$ cargo install --path helix-term --locked
[…]The “–locked” option gave me a very unnerving warning:
warning: package `cc v1.0.85` in Cargo.lock is yanked in registry `crates-io`, consider running without --lockedBut without that option it failed, so I kept the “–locked”.
On my couple year old laptop it took about 5-minutes. First time I tried to build it on a Raspberry Pi Zero W, running inside an emacs shell buffer, it died after filling up all of its 512MB of RAM and 100 MB of “swap”, before it finished. I’m trying again not inside emacs, I’ll let you know.
Also:
$ ln -Ts $PWD/runtime ~/.config/helix/runtimeThat last part is necessary to have syntax highlighting work, etc.
Using Helix, Setting the Stage
I do not find it obvious how to use Helix, but it is based on vim, so what would I expect?
First, how do I even run it? No, typing “helix” will not work. Because that would be too obvious. And because nostalgia and tradition, I suppose, the executable is called “hx”. Run that and you are in. (But do you know how to get back out? Keep reading.)
Second, as it is based on vim (which is based on vi), it is very modal. The design of vi dates back to the beginning of time (1976), when for $5,000 (in today’s dollars) would buy an ADM-3A CRT terminal, which could display 24-lines of 80-characters each! It was the hot new technology, and it didn’t even have dedicated arrow keys. The computer mouse, and graphical user interfaces of any sort, had barely been seen in public. And “power users” would scoff at such silliness for many years to come. This is a modal, keyboard-based interface.
In vi there are two enormous modes. You can be in “insert mode”, where typing “hjkl” results in “hjkl” appearing in your document, or you can be in “normal mode” where pressing “hjkl” moves the cursor left, down, up, and then right. Tending to leave you back where you started.
We are about to get very modal.
Insert Mode and Normal Mode
When you first run Helix you will be in normal mode. In the bottom left corner it will say “NOR” indicating NORmal mode, and when you are in insert mode it will say “INS” for INSert mode.
Time for our first cheat sheet items:
- “i” puts you in insert mode. This is where you can type stuff. (And because current keyboards have arrow keys, more around, too.)
- Type stuff and it will be inserted into your file.
- Arrow keys, pageup, pagedown, home, end, backspace, forward delete all do as you would hope.
- Escape key gets you out of insert mode, back to normal mode, where the letter keys do not type those letters, but do other things. No matter what you are doing in Helix, the escape key seems to generally be a safe thing to press; wherever you are, press it a few times until you will get back to familiar territory.
Command Mode
The normal mode is for single-keystroke stuff. But opening and saving files isn’t single keystroke territory (file names can be long), so there needs to be a command mode that accepts multiple keystrokes.
- “:” command mode commands all begin with colon.
- “:quit” (or “:q“), followed by another press of enter, will quit; though it will stop if you have unsaved changes.
- “:q!” will quit without saving changes. If you are in a panic and need to get out (without saving changes) press escape a couple times “:q!”, then enter, and you will be free again.
- “:write” (or “:w“) will save changes to current file
- “:w somefile.rs” will save to a file called “somefile.rs”.
- “:open differentfile.txt” (or “:o” …) will open a new or existing file called “differentfile.txt”
- :reload (or “:rl“) revert current buffer, discarding any changes.
- Escape will get you out of this mini mode and any command you have partially typed, and put you back to the regular normal mode.
More Normal Mode: Real Cheat Sheet, Finally
At this point I think you know enough to do the most basic editing. Hooray! But only just barely enough. So press escape, to be sure you are back to the normal mode (NOR in the corner), let the cheat sheet begin!
We all make mistakes:
- u – undo
- U – redo
Navigation:
- hjkl - move cursor, pretend those letter keys are labeled: ⇠⇣⇡⇢ (those letters might already be under your fingers, so maybe it is worth learning them, or maybe you are on a vintage ADM-3A terminal with no dedicated arrow keys—but probably just use arrow keys for now).
- w - word forward
- W - WORD (larger concept of word) forward
- b - back one word
- B - back one WORD
- e - end of word
- pageup – page up
- pagedown – page down
- ctrl-u – half page up
- ctrl-d – half page down
- nnnG – goto line nnn
- 4k (or 4 then up arrow) – move up 4-lines, etc.
- /xyz – search forward for “xyz”
- ?xyz – search backwards for “xyz”
Once out of search mode:
- n – next matching search string.
- N – previous matching search string.
Making a selection—another mode:
- v – enter (or leave) select mode
Once you have a selection you can use copy and paste:
- y – copy (yank) selection
- p – paste after selection
- P – paste before selection
- d – delete selection
- x – shortcut to select a line, without being in selection mode.
- xx – select two lines, etc.
- xd – select line, and delete it, etc.
Insert Mode
- ctrl-k Delete to end of line.
- tab When offered a completion item, move to next
Space Bar Mode
When in normal mode, pressing the space bar puts you in an interactive menu world (and the escape key still works to get you out). Press space and cool options appear, each begins with a single letter followed by a little explanatory text, press the space bar again (or press escape or an arrow key) and this menu disappears. Press the key for one of the letters and you will get a new menu. I appreciate that the choices in this menu system appear to be pretty clear and safe to explore. Go take a look.
- f – file picker. Cooler than the “:o” feature of the command mode. Once you are in the list of files up and down keys, page up and down keys, all work as you might hope.
- w – window picker. In here you can split your current window horizontally or vertically. The result is tiled panes not overlapping windows, but that’s a good thing. You can close a window pane. You can move from one of these window panes to another. This is starting to turn into a useful editor!
- b – buffer picker. You can have more than one file open at a time. How many files you have open and how many window panes you have displayed (and what they display) are different things. This editor is getting more useful.
- y, p – more copy and paste features.
- s – symbol picker. Choose from the variables, structs, constants, functions, etc., that you have actually defined, rather than mistyping them from memory.
- S – workplace picker. Like the symbol picker, but seems to only offer the public symbols.
- r – rename. Seems to work one variables, struct names and members, function names, etc. Cool.
- / – global search.
- k – Documentation for whatever thing the cursor is in. (To scroll the result use ctrl-u and crtl-d.)
- a – perform code action. A bunch of very Rust-specific options that you should explore a little, maybe once all this other stuff has settled in.
Conclusion
So far Helix looks good. By being limited to a keyboard and having no GUI, and being based on VIM, it seems a lot more constrained than the other, flashier, disorienting, featuritis-plagued IDEs that I have tried in recent years. The space bar mode is nicely self-documenting, as opposed to all the magic single-key “What did I just do when I bumped that key‽‽” of VS Code or some Jetbrains product. At least for me all this makes Helix a lot easier to learn.
Epilogue
Oh, and my native Raspberry PI Zero W build keeps failing as I try various experiments. I would like this because I’m programming some Pi Zero-specific hardware…
Followups: Syntax Highlighting
I hate low contrast, gray on gray displays, so to have more choices:
$ git clone https://github.com/CptPotato/helix-themes.git
$ cd helix-themes
$ ./build.sh
$ mkdir ~/.config/helix/themes/
$ cp build/* ~/.config/helix/themes/
Now I can select the theme I want by editing ~/.config/helix/config.toml. Um, I think I got my config.toml from configuration section of the Helix docs.
©2024 Kent Borg