Helix, Terminal-based Rust IDE

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

Based on vim? Ugh. I long ago learned vi (and vim) just enough to be able to get it to do basic stuff. Intriguing. Let me give it a try.

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

But 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/runtime

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

Everything is organized around these two big modes: Normal mode, and insert mode.

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.

In Helix pressing “:” will immediately show you lots of available commands, I don’t know what most of them are. I don’t think there is a way navigate through these with arrow keys, and that text seems there merely to guide further typing As you enter more letter keys the number of possible completions will be reduced accordingly. This feels like a dangerous mode to me, because other than the name of the command, I can find no on-screen documentation of these commands. Explore here, but maybe carefully.

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.

Searching:

/xyz – search forward for “xyz”
?xyz – search backwards for “xyz”

Searching is also another mode. While typing your search string Helix will show you the next text that matches your search string so far. Press the enter key and now the search is done. At the point you are back to normal mode.

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

This is a little like holding the mouse -specificdown in a graphical editor, combined with navigation, you can make a selection. A bit like dragging a mouse through text.

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.

At this point you have enough to use Helix as a basic editor: run and quit the program; type stuff; open, save, and close files; navigate through your file; search; copy and paste; undo and redo. Nothing very fancy. Time for another mode, where they seem to keep all the fancy stuff.

Insert Mode

The simplest thing to do in insert mode is to type text. In addition those extra keys that didn’t exist in 1976 also do what you would expect: arrow keys, backspace, forward delete, home, end, page up, page down. Beyond them there are a lot of other things that can be done:

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.

Here are some of the editor things I’ve discovered in my exploring, and exploring here is nice:

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.

Here are—finally—some of the Rust-specific things I have discovered:

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.