Recipes

Includes common solutions to some problems.

Git Integration

Helix comes with basic git integration such as the ability to see which files have been modified on the gutters, and acting on git hunks as text objects. But a more comprehensive git integration can be desired, which is understandable.

Lazygit is the most popular git TUI and you can smoothly integrate it with Helix with the following keymap:

[keys.normal]
C-g = [
    ":write-all",
    ":new",
    ":insert-output lazygit",
    ":buffer-close!",
    ":redraw",
    ":reload-all"
]

Explanation

write-all: save all buffers so that the changes can be shown in lazygit and committed right away
new: create new empty buffer
insert-output lazygit: runs the lazygit command and inserts it’s output into the new buffer
When you exit lazygit, buffer-close! will kill the previously empty buffer, sending you back to where you were previously.
redraw is necessary to re-render the UI to show the buffers
reload-all because if e.g. you commit everything, helix will still show the symbols indicating that lines were changed / deleted on the left of the line numbers. This will prevent that

Remap Caps Lock to Escape

The Esc key is quite far away from the home row on most keyboards. Due to this fact, many people remap Caps Lock to Esc.

To do this, follow instructions for your operating system.

You can use keyd ↗, which is a modern alternative to xmodmap compatible with Wayland and XOrg.

Install keyd using your system’s package manager
Start the keyd daemon:
Terminal window
```
sudo systemctl enable keyd
```

Place the following in /etc/keyd/default.conf

[ids]
*
[main]
# Maps capslock to escape when pressed and control when held.
capslock = overload(control, esc)

# Remaps the escape key to capslock
esc = capslock

Run sudo keyd reload to reload the config set.

AutoHotkey is a free and open source scripting language for Windows, primarily useful for remapping keyboard keys in our example.

Install AutoHotkey from the AutoHotkey installation page ↗.
Create a new remap-caps-lock.ahk file on your desktop.
Right-click on the new script file and select Edit script.
Add this line to the script:
```
CapsLock::Esc
```
Run the script by double-clicking on it. It will start running in the background.

Project-wide Search and Replace

In helix, you can perform search-and-replace in a file by using % to select the whole file and then s to match a regex against the file, placing cursors on each match.

But what if you want to perform a project-wide search and replace? Helix currently doesn’t provide that functionality, but there is an external tool called scooter ↗ which was created exactly for this purpose. Check it out!

Integrated Terminal

At the moment, there’s no way to open a terminal from within Helix. Despite that, many users prefer using Ctrl + z which puts the current process to sleep.

When you run this command from inside Helix, it will be put to sleep. You’ll be able to access the terminal again, browse files, and do everything else you usually do.

Once you need to return back to Helix, you can type fg in the terminal which will bring Helix back from sleep and resume it exactly where you left it. You can use this to run background processes while using Helix, and other shell commands.

If you prefer using Ctrl + z to put Helix to sleep, and then use Ctrl + z to wake it up again instead of using fg, then you can!

Depending on your shell, put a snippet of code into your terminal.

Add the following to your ~/.zshrc:

# Allow Ctrl-z to toggle between suspend and resume
function Resume {
  fg
  zle push-input
  BUFFER=""
  zle accept-line
}
zle -N Resume
bindkey "^Z" Resume

Add the following to your fish config file:

bind \cz 'fg 2>/dev/null; commandline -f repaint'

This is possible since fish v3.2.0 ↗.

Source: Binding CTRL-Z ↗.

Use bash-preexec.sh ↗ to:

Disable the Ctrl-Z keybinding before printing the prompt
Enable the Ctrl-Z keybinding before executing a command

This way, we are able to repurpose Ctrl-Z when in a Bash interactive prompt. But any command ran by Bash will still be able to suspend normally with Ctrl + Z.

You might need to change this path to your bash-preexec.sh location.

source ~/.config/bash/bash-preexec.sh
preexec () {
  stty susp '^Z'
}
precmd () {
  stty susp undef
}

# Bind Ctrl-Z to "fg %-" (resume next to last suspended job, or last if only one)
# This binding works like this:
# - If you have one job, Ctlr-Z will toggle in and out of it.
# - If you have more  jobs, "Ctrl-Z Ctrl-Z" will toggle between the last two.
bind '"\C-z":"fg %-\n"'

More intuitive x and X motions

Some people prefer to remap x and X motions from the defaults:

x = "extend_line_below"
X = "extend_to_line_bounds"

To the following:

x = "select_line_below"
X = "select_line_above"

Due to the fact that they may find it more natural to have x and X perform opposite motions, similar to other motions in Helix.

Currently some people want this to become the default.