Enable the COPR repository for Helix:
sudo dnf copr enable varlad/helix
-sudo dnf install helix
+sudo dnf install helix
Arch Linux extra
Releases are available in the extra repository:
sudo pacman -S helix
+
+๐ก When installed from the extra repository, run Helix with helix instead of hx.
+For example:
+helix --health
+
+to check health
+
Additionally, a helix-git package is available
in the AUR, which builds the master branch.
NixOS
@@ -299,6 +305,9 @@ Download the official Helix AppImage from the Homebrew Core
brew install helix
+MacPorts
+port install helix
+
Windows
Install on Windows using Winget, Scoop, Chocolatey
or MSYS2.
@@ -328,7 +337,7 @@ Linux and macOS, or %userprofile%\src\ on Windows.
A C++14 compatible compiler to build the tree-sitter grammars, for example GCC or Clang
If you are using the musl-libc standard library instead of glibc the following environment variable must be set during the build to ensure tree-sitter grammars can be loaded correctly:
-RUSTFLAGS="-C target-feature=-crt-static"
+RUSTFLAGS="-C target-feature=-crt-static"
-
@@ -346,6 +355,9 @@ grammars in the local
runtime folder.
+๐ก If you do not want to fetch or build grammars, set an environment variable HELIX_DISABLE_AUTO_GRAMMAR_BUILD
+
+
๐ก Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch
grammars with hx --grammar fetch and compile them with
hx --grammar build. This will install them in
@@ -354,10 +366,10 @@ the runtime directory within the user's helix config directory (mor
Configuring Helix's runtime files
Linux and macOS
-The runtime directory is one below the Helix source, so either set a
+
The runtime directory is one below the Helix source, so either export a
HELIX_RUNTIME environment variable to point to that directory and add it to
your ~/.bashrc or equivalent:
-HELIX_RUNTIME=~/src/helix/runtime
+export HELIX_RUNTIME=~/src/helix/runtime
Or, create a symbolic link:
ln -Ts $PWD/runtime ~/.config/helix/runtime
@@ -367,7 +379,7 @@ your ~/.bashrc or equivalent:
Either set the HELIX_RUNTIME environment variable to point to the runtime files using the Windows setting (search for
Edit environment variables for your account) or use the setx command in
Cmd:
-setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
+setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
๐ก %userprofile% resolves to your user directory like
@@ -375,8 +387,8 @@ Cmd:
Or, create a symlink in %appdata%\helix\ that links to the source code directory:
Method Command PowerShell New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"Cmd cd %appdata%\helix
mklink /D runtime "%userprofile%\src\helix\runtime"PowerShell New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"Cmd cd %appdata%\helix
mklink /D runtime "%userprofile%\src\helix\runtime"
@@ -430,8 +442,8 @@ cp contrib/helix.png ~/.icons # or ~/.local/share/icons
To use another terminal than the system default, you can modify the .desktop
file. For example, to use kitty:
-sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
-sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop
+sed -i "s|Exec=hx %F|Exec=kitty hx %F|g" ~/.local/share/applications/Helix.desktop
+sed -i "s|Terminal=true|Terminal=false|g" ~/.local/share/applications/Helix.desktop
Using Helix
@@ -458,19 +470,19 @@ can be accessed via the command hx --tutor or :tutor.<
Registers
In Helix, registers are storage locations for text and other data, such as the
result of a search. Registers can be used to cut, copy, and paste text, similar
-to the clipboard in other text editors. Usage is similar to Vim, with " being
+to the clipboard in other text editors. Usage is similar to Vim, with " being
used to select a register.
User-defined registers
Helix allows you to create your own named registers for storing text, for
example:
-"ay - Yank the current selection to register a."op - Paste the text in register o after the selection."ay - Yank the current selection to register a."op - Paste the text in register o after the selection.
If a register is selected before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:
-"hc - Store the selection in register h and then change it (delete and enter insert mode)."md - Store the selection in register m and delete it."hc - Store the selection in register h and then change it (delete and enter insert mode)."md - Store the selection in register m and delete it.
Default registers
Commands that use registers, like yank (y), use a default register if none is specified.
@@ -478,7 +490,7 @@ These registers are used as defaults:
Register character Contains /Last search :Last executed command "Last yanked text "Last yanked text @Last recorded macro
@@ -489,8 +501,8 @@ These registers are used as defaults:
#Selection indices (first selection is 1, second is 2, etc.) This register is not writable .Contents of the current selections This register is not writable %Name of the current file This register is not writable *Reads from the system clipboard Joins and yanks to the system clipboard +Reads from the primary clipboard Joins and yanks to the primary clipboard +Reads from the system clipboard Joins and yanks to the system clipboard *Reads from the primary clipboard Joins and yanks to the primary clipboard When yanking multiple selections to the clipboard registers, the selections
@@ -560,7 +572,7 @@ documentation.
and requires the corresponding query file to work properly.
Moving the selection with syntax-aware motions
-Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) allow you to move the
+
Alt-p, Alt-o, Alt-i, and Alt-n (or Alt and arrow keys) allow you to move the
selection according to its location in the syntax tree. For example, many languages have the
following syntax for function calls:
func(arg1, arg2, arg3);
@@ -582,12 +594,12 @@ a more intuitive tree format:
โ โ
โโโโโโโผโโโโโ โโโโโโผโโโโโ
โidentifierโ โargumentsโ
-โ "func" โ โโโโโโดโโโโฌโโโโโโดโโโโ
+โ "func" โ โโโโโโดโโโโฌโโโโโโดโโโโ
โโโโโโโโโโโโ โ โ โ
โ โ โ
โโโโโโโโโโโผโ โโโโโโผโโโโโโ โโผโโโโโโโโโโ
โidentifierโ โidentifierโ โidentifierโ
- โ "arg1" โ โ "arg2" โ โ "arg3" โ
+ โ "arg1" โ โ "arg2" โ โ "arg3" โ
โโโโโโโโโโโโ โโโโโโโโโโโโ โโโโโโโโโโโโ
If you have a selection that wraps arg1 (see the tree above), and you use
@@ -606,7 +618,7 @@ node with no sibling. When using Alt-p with a selection on ar
child node will be selected. In the event that arg1 does not have a previous
sibling, the selection will move up the syntax tree and select the previous
element. As a result, using Alt-p with a selection on arg1 will move the
-selection to the "func" identifier.
+selection to the "func" identifier.
Keymap
- Normal mode
@@ -627,6 +639,7 @@ selection to the "func"
identifier.
- Window mode
- Space mode
@@ -647,7 +660,7 @@ selection to the "func" identifier.
๐ก Mappings marked (TS) require a tree-sitter grammar for the file type.
Normal mode
-Normal mode is the default mode when you launch helix. Return to it from other modes by typing Escape.
+Normal mode is the default mode when you launch helix. You can return to it from other modes by pressing the Escape key.
Movement
NOTE: Unlike Vim, f, F, t and T are not confined to the current line.
@@ -668,13 +681,13 @@ selection to the "func" identifier.
TFind 'till previous char till_prev_charFFind previous char find_prev_charGGo to line number <n> goto_lineAlt-.Repeat last motion (f, t or m) repeat_last_motionAlt-.Repeat last motion (f, t, m, [ or ]) repeat_last_motionHomeMove to the start of the line goto_line_startEndMove to the end of the line goto_line_endCtrl-b, PageUpMove page up page_upCtrl-f, PageDownMove page down page_downCtrl-uMove half page up half_page_upCtrl-dMove half page down half_page_downCtrl-uMove cursor and page half page up page_cursor_half_upCtrl-dMove cursor and page half page down page_cursor_half_downCtrl-iJump forward on the jumplist jump_forwardCtrl-oJump backward on the jumplist jump_backwardCtrl-sSave the current selection to the jumplist save_selectionidentifier.
yYank selection yankpPaste after selection paste_afterPPaste before selection paste_before" <reg>Select a register to yank to or paste from select_register" <reg>Select a register to yank to or paste from select_register>Indent selection indent<Unindent selection unindent=Format selection (currently nonfunctional/disabled) (LSP) format_selectionsidentifier.
Search
-Search commands all operate on the / register by default. To use a different register, use "<char>.
+Search commands all operate on the / register by default. To use a different register, use "<char>.
Key Description Command /Search for regex pattern search?Search for previous pattern rsearchidentifier.
View mode
Accessed by typing z in normal mode.
View mode is intended for scrolling and manipulating the view without changing
-the selection. The "sticky" variant of this mode (accessed by typing Z in
+the selection. The "sticky" variant of this mode (accessed by typing Z in
normal mode) is persistent and can be exited using the escape key. This is
useful when you're simply looking over text and not actively editing it.
Key Description Command k, upScroll the view upwards scroll_upCtrl-f, PageDownMove page down page_downCtrl-b, PageUpMove page up page_upCtrl-dMove half page down half_page_downCtrl-uMove half page up half_page_upCtrl-uMove cursor and page half page up page_cursor_half_upCtrl-dMove cursor and page half page down page_cursor_half_down
Goto mode
@@ -810,7 +823,7 @@ useful when you're simply looking over text and not actively editing it.
Key Description Command gGo to line number <n> else start of file goto_file_starteGo to the end of the file goto_last_linefGo to files in the selection goto_filefGo to files in the selections goto_filehGo to the start of the line goto_line_startlGo to the end of the line goto_line_endsGo to first non-whitespace character of the line goto_first_nonwhitespace.Go to last modification in current file goto_last_modificationjMove down textual (instead of visual) line move_line_downkMove up textual (instead of visual) line move_line_upwShow labels at each word and select the word that belongs to the entered labels goto_word
Match mode
@@ -851,8 +865,8 @@ useful when you're simply looking over text and not actively editing it.
w, Ctrl-wSwitch to next window rotate_viewv, Ctrl-vVertical right split vsplits, Ctrl-sHorizontal bottom split hsplitfGo to files in the selection in horizontal splits goto_fileFGo to files in the selection in vertical splits goto_filefGo to files in the selections in horizontal splits goto_fileFGo to files in the selections in vertical splits goto_fileh, Ctrl-h, LeftMove to left split jump_view_leftj, Ctrl-j, DownMove to split below jump_view_downk, Ctrl-k, UpMove to split above jump_view_uphSelect symbol references (LSP) select_references_to_symbol_under_cursor'Open last fuzzy picker last_pickerwEnter window mode N/A cComment/uncomment selections toggle_commentsCBlock comment/uncomment selections toggle_block_commentsAlt-cLine comment/uncomment selections toggle_line_commentspPaste system clipboard after selections paste_clipboard_afterPPaste system clipboard before selections paste_clipboard_beforeyYank selections to clipboard yank_to_clipboardAs you become more comfortable with modal editing, you may want to disable some
insert mode bindings. You can do this by editing your config.toml file.
[keys.insert]
-up = "no_op"
-down = "no_op"
-left = "no_op"
-right = "no_op"
-pageup = "no_op"
-pagedown = "no_op"
-home = "no_op"
-end = "no_op"
+up = "no_op"
+down = "no_op"
+left = "no_op"
+right = "no_op"
+pageup = "no_op"
+pagedown = "no_op"
+home = "no_op"
+end = "no_op"
Select / extend mode
Accessed by typing v in normal mode.
@@ -1055,7 +1072,7 @@ you to selectively add search terms to your selections.
:write-buffer-close!, :wbc!Force write changes to disk creating necessary subdirectories and closes the buffer. Accepts an optional path (:write-buffer-close! some/path.txt) :new, :nCreate a new scratch buffer. :format, :fmtFormat the file using the LSP formatter. :indent-styleSet the indentation style for editing. ('t' for tabs or 1-8 for number of spaces.) :indent-styleSet the indentation style for editing. ('t' for tabs or 1-16 for number of spaces.) :line-endingSet the document's default line ending. Options: crlf, lf. :earlier, :earJump back to an earlier point in edit history. Accepts a number of steps or a time span. :later, :latJump to a later point in edit history. Accepts a number of steps or a time span. :reset-diff-change, :diffget, :diffgReset the diff change at the cursor position. :clear-registerClear given register. If no argument is provided, clear all registers. :redrawClear and re-render the whole UI :moveMove the current buffer and its corresponding file to a different path :yank-diagnosticYank diagnostic(s) under primary cursor to register, or clipboard by default
Language Support
The following languages and Language Servers are supported. To use
@@ -1132,6 +1151,8 @@ appropriate Language Server.
Also see the Language Configuration docs and the Adding
Languages guide for more language configuration information.
Language Syntax Highlighting Treesitter Textobjects Auto Indent Rainbow Brackets Default LSP ada โ โ ada_language_server, ada_language_serveragda โ astro โ awk โ โ awk-language-serverbash โ โ โ โ bash-language-serverbeancount โ bibtex โ texlabbicep โ bicep-langserverblade โ blueprint โ blueprint-compilerc โ โ โ โ clangdc-sharp โ โ OmniSharpcabal cabal haskell-language-server-wrappercairo โ โ โ cairo-language-servercapnp โ โ cel โ clojure โ โ clojure-lspcmake โ โ โ cmake-language-servercomment โ common-lisp โ โ cl-lspcommon-lisp โ โ โ cl-lspcpon โ โ cpp โ โ โ โ clangdcrystal โ โ crystallinecss โ โ vscode-css-language-servercss โ โ โ vscode-css-language-servercue โ cuelspd โ โ โ serve-ddart โ โ dartdart โ โ โ dartdbml โ devicetree โ dhall โ โ dhall-lsp-serverdiff โ docker-compose โ โ docker-compose-langserver, yaml-language-serverdockerfile โ docker-langserverdot โ dot-language-serverdtd โ erb โ erlang โ โ โ erlang_lsesdl โ fidl โ fish โ โ โ forth โ forth-lspfortran โ โ fortlsgit-config โ git-ignore โ git-rebase โ gleam โ โ gleamgleam โ โ โ gleamglimmer โ ember-language-serverglsl โ โ โ go โ โ โ โ goplsgn โ go โ โ โ โ gopls, golangci-lint-langservergodot-resource โ gomod โ goplsgotmpl โ goplsgowork โ goplsgraphql โ graphql-lspgroovy โ hare โ haskell โ โ haskell-language-server-wrapperhaskell-persistent โ hcl โ โ terraform-lshcl โ โ โ terraform-lsheex โ โ elixir-lshelm โ helm_lshocon โ โ hoon โ hosts โ html โ โ vscode-html-language-serverhurl โ โ hyprlang โ โ idris idris2-lspiex โ ini โ janet โ java โ โ โ โ jdtlsjavascript โ โ โ โ typescript-language-serverjinja โ jsdoc โ json โ โ โ vscode-json-language-serverjson5 โ jsonc โ โ vscode-json-language-serverjsonnet โ jsonnet-language-serverjsx โ โ โ โ typescript-language-serverjulia โ โ โ juliajust โ โ โ kdl โ kdl โ โ โ koka โ โ kokakotlin โ kotlin-language-serverlatex โ โ texlabld โ โ lean โ leanledger โ llvm โ โ โ llvm-mir โ โ โ llvm-mir-yaml โ โ log โ lpf โ lua โ โ โ lua-language-servermake โ make โ โ markdoc โ markdoc-lsmarkdown โ marksmanmarkdown โ marksman, markdown-oxidemarkdown.inline โ matlab โ โ โ mermaid โ nasm โ โ nickel โ โ nlsnim โ โ โ nimlangservernix โ โ nilnu โ nix โ โ โ nilnu โ nununjucks โ ocaml โ โ ocamllspocaml-interface โ ocamllspodin โ โ olsohm โ โ โ opencl โ โ โ clangdopenscad โ openscad-lsporg โ pem โ perl โ โ โ perlnavigatorphp โ โ โ intelephensephp-only โ pkgbuild โ โ โ pkgbuild-language-server, bash-language-serverpkl โ โ po โ โ pod โ ponylang โ โ โ powershell โ prisma โ prisma-language-serverprolog swiplprotobuf โ โ bufls, pbprotobuf โ โ โ bufls, pbprql โ purescript โ โ purescript-language-serverpython โ โ โ โ pylspqml โ โ qmllsr โ Rracket โ โ racketracket โ โ โ racketregex โ โ rego โ regolsrescript โ โ rescript-language-serverruby โ โ โ โ solargraphrust โ โ โ โ rust-analyzersage โ โ scala โ โ metalsscheme โ โ scala โ โ โ metalsscheme โ โ โ scss โ โ vscode-css-language-serverslint โ โ slint-lspslint โ โ โ slint-lspsmali โ โ smithy โ cssml โ solidity โ solcspicedb โ sql โ sshclientconfig โ starlark โ โ โ strace โ supercollider โ svelte โ โ svelteserversway โ โ โ forcswift โ sourcekit-lspt32 โ tablegen โ โ โ tact โ โ โ task โ templ โ templtfvars โ โ terraform-lstsx โ โ โ โ typescript-language-servertwig โ typescript โ โ โ โ typescript-language-servertypst โ typst-lspungrammar โ unison โ unison โ โ uxntal โ v โ โ โ v-analyzervala โ vala-language-servervala โ โ vala-language-serververilog โ โ svlangservervhdl โ vhdl_lsvhs โ ๐ก You can easily open the config file by typing :config-open within Helix normal mode.
Example config:
-theme = "onedark"
+theme = "onedark"
[editor]
-line-number = "relative"
+line-number = "relative"
mouse = false
[editor.cursor-shape]
-insert = "bar"
-normal = "block"
-select = "underline"
+insert = "bar"
+normal = "block"
+select = "underline"
[editor.file-picker]
hidden = false
@@ -1364,15 +1413,16 @@ Its settings will be merged with the configuration directory config.tomlmouseEnable mouse mode truemiddle-click-pasteMiddle click paste support truescroll-linesNumber of lines to scroll per scroll wheel step 3shellShell to use when running external commands Unix: ["sh", "-c"]
Windows: ["cmd", "/C"] shellShell to use when running external commands Unix: ["sh", "-c"]
Windows: ["cmd", "/C"] line-numberLine number display: absolute simply shows each line's number, while relative shows the distance from the current line. When unfocused or in insert mode, relative will still show absolute line numbers absolutecursorlineHighlight all lines with a cursor falsecursorcolumnHighlight all columns with a cursor falseguttersGutters to display: Available are diagnostics and diff and line-numbers and spacer, note that diagnostics also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]guttersGutters to display: Available are diagnostics and diff and line-numbers and spacer, note that diagnostics also includes other features like breakpoints, 1-width padding will be inserted if gutters is non-empty ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]auto-completionEnable automatic pop up of auto-completion trueauto-formatEnable automatic formatting on save trueauto-saveEnable automatic saving on the focus moving away from Helix. Requires focus event support from your terminal falseidle-timeoutTime in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant 400idle-timeoutTime in milliseconds since last keypress before idle timers trigger. 250completion-timeoutTime in milliseconds after typing a word character before completions are shown, set to 5 for instant. 250preview-completion-insertWhether to apply completion item instantly when selected truecompletion-trigger-lenThe min-length of word under cursor to trigger autocompletion 2completion-replaceSet to true to make completions always replace the entire word and not just the part before the cursor falseconfig.tomlundercurlSet to true to override automatic detection of terminal undercurl support in the event of a false negative falserulersList of column positions at which to display the rulers. Can be overridden by language specific rulers in languages.toml file []bufferlineRenders a line at the top of the editor displaying open buffers. Can be always, never or multiple (only shown if more than one buffer is in use) neverinitial-modeThe initial mode for newly opened editors. "normal"color-modesWhether to color the mode indicator with different colors depending on the mode itself falsetext-widthMaximum line length. Used for the :reflow command and soft-wrapping if soft-wrap.wrap-at-text-width is set 80workspace-lsp-rootsDirectories relative to the workspace root that are treated as LSP roots. Should only be set in .helix/config.toml []default-line-endingThe line ending to use for new documents. Can be native, lf, crlf, ff, cr or nel. native uses the platform's native line ending (crlf on Windows, otherwise lf). nativeinsert-final-newlineWhether to automatically insert a trailing line-ending on write if missing truepopup-borderDraw border around popup, menu, all, or none noneindent-heuristicHow the indentation for a newly inserted line is computed: simple just copies the indentation level from the previous line, tree-sitter computes the indentation based on the syntax tree and hybrid combines both approaches. If the chosen heuristic is not available, a different one will be used as a fallback (the fallback order being hybrid -> tree-sitter -> simple). hybridjump-label-alphabetThe characters that are used to generate two character jump labels. Characters at the start of the alphabet are used first. "abcdefghijklmnopqrstuvwxyz"initial-modeThe initial mode for newly opened editors. "normal"rainbow-bracketsWhether to render rainbow colors for matching brackets. Requires tree-sitter rainbows.scm queries for the language. false
[editor.statusline] Section
Allows configuring the statusline at the bottom of the editor.
The configuration distinguishes between three areas of the status line:
-[ ... ... LEFT ... ... | ... ... ... ... CENTER ... ... ... ... | ... ... RIGHT ... ... ]
+[ ... ... LEFT ... ... | ... ... ... CENTER ... ... ... | ... ... RIGHT ... ... ]
Statusline elements can be defined as follows:
[editor.statusline]
-left = ["mode", "spinner"]
-center = ["file-name"]
-right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"]
-separator = "โ"
-mode.normal = "NORMAL"
-mode.insert = "INSERT"
-mode.select = "SELECT"
+left = ["mode", "spinner"]
+center = ["file-name"]
+right = ["diagnostics", "selections", "position", "file-encoding", "file-line-ending", "file-type"]
+separator = "โ"
+mode.normal = "NORMAL"
+mode.insert = "INSERT"
+mode.select = "SELECT"
The [editor.statusline] key takes the following sub-keys:
Key Description Default leftA list of elements aligned to the left of the statusline ["mode", "spinner", "file-name", "read-only-indicator", "file-modification-indicator"]leftA list of elements aligned to the left of the statusline ["mode", "spinner", "file-name", "read-only-indicator", "file-modification-indicator"]centerA list of elements aligned to the middle of the statusline []rightA list of elements aligned to the right of the statusline ["diagnostics", "selections", "register", "position", "file-encoding"]separatorThe character used to separate elements in the statusline "โ"mode.normalThe text shown in the mode element for normal mode "NOR"mode.insertThe text shown in the mode element for insert mode "INS"mode.selectThe text shown in the mode element for select mode "SEL"rightA list of elements aligned to the right of the statusline ["diagnostics", "selections", "register", "position", "file-encoding"]separatorThe character used to separate elements in the statusline "โ"mode.normalThe text shown in the mode element for normal mode "NOR"mode.insertThe text shown in the mode element for insert mode "INS"mode.selectThe text shown in the mode element for select mode "SEL"
The following statusline elements can be configured:
@@ -1420,6 +1473,7 @@ mode.select = "SELECT"
modeThe current editor mode (mode.normal/mode.insert/mode.select) spinnerA progress spinner indicating LSP activity file-nameThe path/name of the opened file file-absolute-pathThe absolute path/name of the opened file file-base-nameThe basename of the opened file file-modification-indicatorThe indicator to show whether the file is modified (a [+] appears when there are unsaved changes) file-encodingThe encoding of the opened file if it differs from UTF-8 primary-selection-lengthThe number of characters currently in primary selection positionThe cursor position position-percentageThe cursor position as a percentage of the total number of lines separatorThe string defined in editor.statusline.separator (defaults to "โ") separatorThe string defined in editor.statusline.separator (defaults to "โ") spacerInserts a space between elements (multiple/contiguous spacers may be specified) version-controlThe current branch name or detached commit hash of the opened workspace registerThe current selected register All git related options are only enabled in a git repository.
Key Description Default hiddenEnables ignoring hidden files true follow-symlinksFollow symlinks instead of ignoring them true deduplicate-linksIgnore symlinks that point at files already shown in the picker true parentsEnables reading ignore files from parent directories true ignoreEnables reading .ignore files true git-ignoreEnables reading .gitignore files true git-globalEnables reading global .gitignore, whose path is specified in git's config: core.excludefile option true git-excludeEnables reading .git/info/exclude files true max-depthSet with an integer value for maximum depth to recurse Defaults to None. hiddenEnables ignoring hidden files truefollow-symlinksFollow symlinks instead of ignoring them truededuplicate-linksIgnore symlinks that point at files already shown in the picker trueparentsEnables reading ignore files from parent directories trueignoreEnables reading .ignore files truegit-ignoreEnables reading .gitignore files truegit-globalEnables reading global .gitignore, whose path is specified in git's config: core.excludesfile option truegit-excludeEnables reading .git/info/exclude files truemax-depthSet with an integer value for maximum depth to recurse Unset by default
+Ignore files can be placed locally as .ignore or put in your home directory as ~/.ignore. They support the usual ignore and negative ignore (unignore) rules used in .gitignore files.
+Additionally, you can use Helix-specific ignore files by creating a local .helix/ignore file in the current workspace or a global ignore file located in your Helix config directory:
+
+- Linux and Mac:
~/.config/helix/ignore
+- Windows:
%AppData%\helix\ignore
+
+Example:
+# unignore in file picker and global search
+!.github/
+!.gitignore
+!.gitattributes
+
[editor.auto-pairs] Section
Enables automatic insertion of pairs to parentheses, brackets, etc. Can be a
simple boolean value, or a specific mapping of pairs of single characters.
@@ -1492,28 +1558,28 @@ simple boolean value, or a specific mapping of pairs of single characters.
[editor]
auto-pairs = false # defaults to `true`
-The default pairs are (){}[]''""``, but these can be customized by
+
The default pairs are (){}[]''""``, but these can be customized by
setting auto-pairs to a TOML table:
[editor.auto-pairs]
'(' = ')'
'{' = '}'
'[' = ']'
-'"' = '"'
+'"' = '"'
'`' = '`'
'<' = '>'
Additionally, this setting can be used in a language config. Unless
the editor setting is false, this will override the editor config in
documents with this language.
-Example languages.toml that adds <> and removes ''
+Example languages.toml that adds <> and removes ''
[[language]]
-name = "rust"
+name = "rust"
[language.auto-pairs]
'(' = ')'
'{' = '}'
'[' = ']'
-'"' = '"'
+'"' = '"'
'`' = '`'
'<' = '>'
@@ -1527,25 +1593,28 @@ name = "rust"
[editor.whitespace] Section
Options for rendering whitespace with visible characters. Use :set whitespace.render all to temporarily enable visible whitespace.
Key Description Default renderWhether to render whitespace. May either be "all" or "none", or a table with sub-keys space, nbsp, tab, and newline "none"charactersLiteral characters to use when rendering whitespace. Sub-keys may be any of tab, space, nbsp, newline or tabpad See example below renderWhether to render whitespace. May either be all or none, or a table with sub-keys space, nbsp, nnbsp, tab, and newline nonecharactersLiteral characters to use when rendering whitespace. Sub-keys may be any of tab, space, nbsp, nnbsp, newline or tabpad See example below
Example
[editor.whitespace]
-render = "all"
+render = "all"
# or control each character
[editor.whitespace.render]
-space = "all"
-tab = "all"
-newline = "none"
+space = "all"
+tab = "all"
+nbsp = "none"
+nnbsp = "none"
+newline = "none"
[editor.whitespace.characters]
-space = "ยท"
-nbsp = "โฝ"
-tab = "โ"
-newline = "โ"
-tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending on tab width)
+space = "ยท"
+nbsp = "โฝ"
+nnbsp = "โฃ"
+tab = "โ"
+newline = "โ"
+tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending on tab width)
[editor.indent-guides] Section
Options for rendering vertical indent guides.
@@ -1559,26 +1628,26 @@ tabpad = "ยท" # Tabs will look like "โยทยทยท" (depending o
Example:
[editor.indent-guides]
render = true
-character = "โ" # Some characters that work well: "โ", "โ", "โ", "โธฝ"
+character = "โ" # Some characters that work well: "โ", "โ", "โ", "โธฝ"
skip-levels = 1
-rainbow-option = "normal"
+rainbow-option = "normal"
[editor.gutters] Section
For simplicity, editor.gutters accepts an array of gutter types, which will
use default settings for all gutter components.
[editor]
-gutters = ["diff", "diagnostics", "line-numbers", "spacer"]
+gutters = ["diff", "diagnostics", "line-numbers", "spacer"]
To customize the behavior of gutters, the [editor.gutters] section must
be used. This section contains top level settings, as well as settings for
specific gutter components as subsections.
Key Description Default layoutA vector of gutters to display ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]layoutA vector of gutters to display ["diagnostics", "spacer", "line-numbers", "spacer", "diff"]
Example:
[editor.gutters]
-layout = ["diff", "diagnostics", "line-numbers", "spacer"]
+layout = ["diff", "diagnostics", "line-numbers", "spacer"]
[editor.gutters.line-numbers] Section
Options for the line number gutter
@@ -1593,7 +1662,10 @@ min-width = 1
[editor.gutters.diagnostics] Section
Currently unused
[editor.gutters.diff] Section
-Currently unused
+The diff gutter option displays colored bars indicating whether a git diff represents that a line was added, removed or changed.
+These colors are controlled by the theme attributes diff.plus, diff.minus and diff.delta.
+Other diff providers will eventually be supported by a future plugin system.
+There are currently no options for this section.
[editor.gutters.spacer] Section
Currently unused
[editor.soft-wrap] Section
@@ -1611,7 +1683,26 @@ min-width = 1
enable = true
max-wrap = 25 # increase value to reduce forced mid-word wrapping
max-indent-retain = 0
-wrap-indicator = "" # set wrap-indicator to "" to hide it
+wrap-indicator = "" # set wrap-indicator to "" to hide it
+
+[editor.smart-tab] Section
+Options for navigating and editing using tab key.
+Key Description Default enableIf set to true, then when the cursor is in a position with non-whitespace to its left, instead of inserting a tab, it will run move_parent_node_end. If there is only whitespace to the left, then it inserts a tab as normal. With the default bindings, to explicitly insert a tab character, press Shift-tab. truesupersede-menuNormally, when a menu is on screen, such as when auto complete is triggered, the tab key is bound to cycling through the items. This means when menus are on screen, one cannot use the tab key to trigger the smart-tab command. If this option is set to true, the smart-tab command always takes precedence, which means one cannot use the tab key to cycle through menu items. One of the other bindings must be used instead, such as arrow keys or C-n/C-p. false
+
+Due to lack of support for S-tab in some terminals, the default keybindings don't fully embrace smart-tab editing experience. If you enjoy smart-tab navigation and a terminal that supports the Enhanced Keyboard protocol, consider setting extra keybindings:
+[keys.normal]
+tab = "move_parent_node_end"
+S-tab = "move_parent_node_start"
+
+[keys.insert]
+S-tab = "move_parent_node_start"
+
+[keys.select]
+tab = "extend_parent_node_end"
+S-tab = "extend_parent_node_start"
[editor.explorer] Section
Sets explorer side width and style.
@@ -1620,38 +1711,32 @@ wrap-indicator = "" # set wrap-indicator to "" to hide it
positionexplorer widget position, left or right left[editor.smart-tab] Section
-Key Description Default enableIf set to true, then when the cursor is in a position with non-whitespace to its left, instead of inserting a tab, it will run move_parent_node_end. If there is only whitespace to the left, then it inserts a tab as normal. With the default bindings, to explicitly insert a tab character, press Shift-tab. truesupersede-menuNormally, when a menu is on screen, such as when auto complete is triggered, the tab key is bound to cycling through the items. This means when menus are on screen, one cannot use the tab key to trigger the smart-tab command. If this option is set to true, the smart-tab command always takes precedence, which means one cannot use the tab key to cycle through menu items. One of the other bindings must be used instead, such as arrow keys or C-n/C-p. false
-
[editor.digraphs] Section
By default, special characters can be input using the insert_digraphs command, bound to \ in normal mode.
Custom digraphs can be added to the editor.digraphs section of the config.
[editor.digraphs]
-ka = "ใ"
-ku = { symbols = "ใ", description = "The japanese character Ku" }
-shrug = "ยฏ\\_(ใ)_/ยฏ"
+ka = "ใ"
+ku = { symbols = "ใ", description = "The japanese character Ku" }
+shrug = "ยฏ\\_(ใ)_/ยฏ"
Themes
-To use a theme add theme = "<name>" to the top of your config.toml file, or select it during runtime using :theme <name>.
+To use a theme add theme = "<name>" to the top of your config.toml file, or select it during runtime using :theme <name>.
Creating a theme
Create a file with the name of your theme as the file name (i.e mytheme.toml) and place it in your themes directory (i.e ~/.config/helix/themes or %AppData%\helix\themes on Windows). The directory might have to be created beforehand.
-๐ก The names "default" and "base16_default" are reserved for built-in themes
+
๐ก The names "default" and "base16_default" are reserved for built-in themes
and cannot be overridden by user-defined themes.
Overview
Each line in the theme file is specified as below:
-key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }
+key = { fg = "#ffffff", bg = "#000000", underline = { color = "#ff0000", style = "curl"}, modifiers = ["bold", "italic"] }
Where key represents what you want to style, fg specifies the foreground color, bg the background color, underline the underline style/color, and modifiers is a list of style modifiers. bg, underline and modifiers can be omitted to defer to the defaults.
To specify only the foreground color:
-key = "#ffffff"
+key = "#ffffff"
If the key contains a dot '.', it must be quoted to prevent it being parsed as a dotted key.
-"key.key" = "#ffffff"
+"key.key" = "#ffffff"
For inspiration, you can find the default theme.toml
here and
@@ -1666,12 +1751,12 @@ user-submitted themes
It's recommended to define a palette of named colors, and refer to them in the
configuration values in your theme. To do this, add a table called
palette to your theme file:
-"ui.background" = "white"
-"ui.text" = "black"
+"ui.background" = "white"
+"ui.text" = "black"
[palette]
-white = "#ffffff"
-black = "#000000"
+white = "#ffffff"
+black = "#000000"
Keep in mind that the [palette] table includes all keys after its header,
so it should be defined after the normal theme options.
@@ -1715,7 +1800,7 @@ your terminal emulator.
๐ก The underlined modifier is deprecated and only available for backwards compatibility.
-Its behavior is equivalent to setting underline.style="line".
+Its behavior is equivalent to setting underline.style="line".
Underline style
One of the following values may be used as a value for underline.style, providing it is
@@ -1730,19 +1815,19 @@ supported by your terminal emulator.
Inheritance
Extend other themes by setting the inherits property to an existing theme.
-inherits = "boo_berry"
+inherits = "boo_berry"
-# Override the theming for "keyword"s:
-"keyword" = { fg = "gold" }
+# Override the theming for "keyword"s:
+"keyword" = { fg = "gold" }
# Override colors in the palette:
[palette]
-berry = "#2A2A4D"
+berry = "#2A2A4D"
Rainbow
The rainbow key is used for rainbow highlight for matching brackets.
The key is a list of styles.
-rainbow = ["#ff0000", "#ffa500", "#fff000", { fg = "#00ff00", modifiers = ["bold"] }]
+rainbow = ["#ff0000", "#ffa500", "#fff000", { fg = "#00ff00", modifiers = ["bold"] }]
Colors from the palette and modifiers may be used.
Scopes
@@ -1761,6 +1846,7 @@ The key is a list of styles.
type - Types
builtin - Primitive types provided by the language (int, usize)parameter - Generic type parameters (T)enum
variantui.statusline.insertStatusline mode during insert mode (only if editor.color-modes is enabled) ui.statusline.selectStatusline mode during select mode (only if editor.color-modes is enabled) ui.statusline.separatorSeparator character in statusline ui.bufferlineStyle for the buffer line ui.bufferline.activeStyle for the active buffer in buffer line ui.bufferline.backgroundStyle for bufferline background ui.popupDocumentation popups (e.g. Space + k) ui.popup.infoPrompt for multiple key options ui.windowBorderlines separating splits ui.helpDescription box for commands ui.textCommand prompts, popup text, etc. ui.textDefault text style, command prompts, popup text, etc. ui.text.focusThe currently selected line in the picker ui.text.inactiveSame as ui.text but when the text is inactive (e.g. suggestions) ui.text.infoThe key: command text in ui.popup.info boxes ui.virtual.inlay-hint.parameterStyle for inlay hints of kind parameter (LSPs are not required to set a kind) ui.virtual.inlay-hint.typeStyle for inlay hints of kind type (LSPs are not required to set a kind) ui.virtual.wrapSoft-wrap indicator (see the editor.soft-wrap config) ui.virtual.jump-labelStyle for virtual jump labels ui.menuCode and command completion menus ui.menu.selectedSelected autocomplete item ui.menu.scrollfg sets thumb color, bg sets track color of scrollbardiagnostic.infoDiagnostics info (editing area) diagnostic.warningDiagnostics warning (editing area) diagnostic.errorDiagnostics error (editing area) diagnostic.unnecessaryDiagnostics with unnecessary tag (editing area) diagnostic.deprecatedDiagnostics with deprecated tag (editing area) Key remapping
Helix currently supports one-way key remapping through a simple TOML configuration
@@ -2043,59 +2135,59 @@ directory (default ~/.config/helix on Linux systems) with a structu
this:
# At most one section each of 'keys.normal', 'keys.insert' and 'keys.select'
[keys.normal]
-C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file)
-C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file
-a = "move_char_left" # Maps the 'a' key to the move_char_left command
-w = "move_line_up" # Maps the 'w' key move_line_up
-"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line
-g = { a = "code_action" } # Maps `ga` to show possible code actions
-"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode
+C-s = ":w" # Maps Ctrl-s to the typable command :w which is an alias for :write (save file)
+C-o = ":open ~/.config/helix/config.toml" # Maps Ctrl-o to opening of the helix config file
+a = "move_char_left" # Maps the 'a' key to the move_char_left command
+w = "move_line_up" # Maps the 'w' key move_line_up
+"C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line
+g = { a = "code_action" } # Maps `ga` to show possible code actions
+"ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode
[keys.insert]
-"A-x" = "normal_mode" # Maps Alt-X to enter normal mode
-j = { k = "normal_mode" } # Maps `jk` to exit insert mode
+"A-x" = "normal_mode" # Maps Alt-X to enter normal mode
+j = { k = "normal_mode" } # Maps `jk` to exit insert mode
Minor modes
Minor modes are accessed by pressing a key (usually from normal mode), giving access to dedicated bindings. Bindings
can be modified or added by nesting definitions.
[keys.insert.j]
-k = "normal_mode" # Maps `jk` to exit insert mode
+k = "normal_mode" # Maps `jk` to exit insert mode
[keys.normal.g]
-a = "code_action" # Maps `ga` to show possible code actions
+a = "code_action" # Maps `ga` to show possible code actions
# invert `j` and `k` in view mode
[keys.normal.z]
-j = "scroll_up"
-k = "scroll_down"
+j = "scroll_up"
+k = "scroll_down"
# create a new minor mode bound to `+`
-[keys.normal."+"]
-m = ":run-shell-command make"
-c = ":run-shell-command cargo build"
-t = ":run-shell-command cargo test"
+[keys.normal."+"]
+m = ":run-shell-command make"
+c = ":run-shell-command cargo build"
+t = ":run-shell-command cargo test"
Special keys and modifiers
Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes
C-, S- and A-. Special keys are encoded as follows:
Key name Representation Backspace "backspace"Space "space"Return/Enter "ret"- "minus"Left "left"Right "right"Up "up"Down "down"Home "home"End "end"Page Up "pageup"Page Down "pagedown"Tab "tab"Delete "del"Insert "ins"Null "null"Escape "esc"Backspace "backspace"Space "space"Return/Enter "ret"- "minus"Left "left"Right "right"Up "up"Down "down"Home "home"End "end"Page Up "pageup"Page Down "pagedown"Tab "tab"Delete "del"Insert "ins"Null "null"Escape "esc"
Keys can be disabled by binding them to the no_op command.
@@ -2104,15 +2196,15 @@ t = ":run-shell-command cargo test"
# Only these normal mode bindings will be used
[keys.normal]
-n = "normal_mode"
-t = "goto_definition"
+n = "normal_mode"
+t = "goto_definition"
# remember to add bindings to return to normal mode
[keys.select]
-esc = "normal_mode"
+esc = "normal_mode"
[keys.insert]
-esc = "normal_mode"
+esc = "normal_mode"
A list of commands is available in the Keymap documentation
and in the source code at helix-term/src/commands.rs at the invocation of static_commands! macro and the TypableCommandList.
@@ -2134,10 +2226,10 @@ auto-LSP-formatting in Rust:
# in <config_dir>/helix/languages.toml
[language-server.mylang-lsp]
-command = "mylang-lsp"
+command = "mylang-lsp"
[[language]]
-name = "rust"
+name = "rust"
auto-format = false
Each language is configured by adding a [[language]] section to a
languages.toml file. For example:
[[language]]
-name = "mylang"
-scope = "source.mylang"
-injection-regex = "mylang"
-file-types = ["mylang", "myl"]
-comment-token = "#"
-indent = { tab-width = 2, unit = " " }
-formatter = { command = "mylang-formatter" , args = ["--stdin"] }
-language-servers = [ "mylang-lsp" ]
+name = "mylang"
+scope = "source.mylang"
+injection-regex = "mylang"
+file-types = ["mylang", "myl"]
+comment-tokens = "#"
+indent = { tab-width = 2, unit = " " }
+formatter = { command = "mylang-formatter" , args = ["--stdin"] }
+language-servers = [ "mylang-lsp" ]
These configuration keys are available:
| Key | Description |
|---|---|
language-id | The language-id for language servers, checkout the table at TextDocumentItem for the right id |
scope | A string like source.js that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually source.<name> or text.<name> in case of markup languages |
injection-regex | regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential language injection site. |
file-types | The filetypes of the language, for example ["yml", "yaml"]. See the file-type detection section below. |
shebangs | The interpreters from the shebang line, for example ["sh", "bash"] |
file-types | The filetypes of the language, for example ["yml", "yaml"]. See the file-type detection section below. |
shebangs | The interpreters from the shebang line, for example ["sh", "bash"] |
roots | A set of marker files to look for when trying to find the workspace root. For example Cargo.lock, yarn.lock |
auto-format | Whether to autoformat this language when saving |
diagnostic-severity | Minimal severity of diagnostic for it to be displayed. (Allowed values: Error, Warning, Info, Hint) |
comment-token | The token to use as a comment-token |
indent | The indent to use. Has sub keys unit (the text inserted into the document when indenting; usually set to N spaces or "\t" for tabs) and tab-width (the number of spaces rendered for a tab) |
comment-tokens | The tokens to use as a comment token, either a single token "//" or an array ["//", "///", "//!"] (the first token will be used for commenting). Also configurable as comment-token for backwards compatibility |
block-comment-tokens | The start and end tokens for a multiline comment either an array or single table of { start = "/*", end = "*/"}. The first set of tokens will be used for commenting, any pairs in the array can be uncommented |
indent | The indent to use. Has sub keys unit (the text inserted into the document when indenting; usually set to N spaces or "\t" for tabs) and tab-width (the number of spaces rendered for a tab) |
language-servers | The Language Servers used for this language. See below for more information in the section Configuring Language Servers for a language |
grammar | The tree-sitter grammar to use (defaults to the value of name) |
formatter | The formatter for the language, it will take precedence over the lsp when defined. The formatter must be able to take the original file as input from stdin and write the formatted file to stdout |
soft-wrap | editor.softwrap |
text-width | Maximum line length. Used for the :reflow command and soft-wrapping if soft-wrap.wrap-at-text-width is set, defaults to editor.text-width |
workspace-lsp-roots | Directories relative to the workspace root that are treated as LSP roots. Should only be set in .helix/config.toml. Overwrites the setting of the same name in config.toml if set. |
persistent-diagnostic-sources | An array of LSP diagnostic sources assumed unchanged when the language server resends the same set of diagnostics. Helix can track the position for these diagnostics internally instead. Useful for diagnostics that are recomputed on save. |
rulers | Overrides the editor.rulers config key for the language. |
rainbow-brackets | Overrides the editor.rainbow-brackets config key for the language. |
Helix determines which language configuration to use based on the file-types key
from the above section. file-types is a list of strings or tables, for
example:
file-types = ["Makefile", "toml", { suffix = ".git/config" }]
+file-types = ["toml", { glob = "Makefile" }, { glob = ".git/config" }, { glob = ".github/workflows/*.yaml" } ]
When determining a language configuration to use, Helix searches the file-types
with the following priorities:
-- Exact match: if the filename of a file is an exact match of a string in a
-
file-types list, that language wins. In the example above, "Makefile"
-will match against Makefile files.
-- Extension: if there are no exact matches, any
file-types string that
-matches the file extension of a given file wins. In the example above, the
-"toml" matches files like Cargo.toml or languages.toml.
-- Suffix: if there are still no matches, any values in
suffix tables
-are checked against the full path of the given file. In the example above,
-the { suffix = ".git/config" } would match against any config files
-in .git directories. Note: / is used as the directory separator but is
-replaced at runtime with the appropriate path separator for the operating
-system, so this rule would match against .git\config files on Windows.
+- Glob: values in
glob tables are checked against the full path of the given
+file. Globs are standard Unix-style path globs (e.g. the kind you use in Shell)
+and can be used to match paths for a specific prefix, suffix, directory, etc.
+In the above example, the { glob = "Makefile" } config would match files
+with the name Makefile, the { glob = ".git/config" } config would match
+config files in .git directories, and the { glob = ".github/workflows/*.yaml" }
+config would match any yaml files in .github/workflow directories. Note
+that globs should always use the Unix path separator / even on Windows systems;
+the matcher will automatically take the machine-specific separators into account.
+If the glob isn't an absolute path or doesn't already start with a glob prefix,
+*/ will automatically be added to ensure it matches for any subdirectory.
+- Extension: if there are no glob matches, any
file-types string that matches
+the file extension of a given file wins. In the example above, the "toml"
+config matches files like Cargo.toml or languages.toml.
Language Server configuration
Language servers are configured separately in the table language-server in the same file as the languages languages.toml
For example:
[language-server.mylang-lsp]
-command = "mylang-lsp"
-args = ["--stdio"]
+command = "mylang-lsp"
+args = ["--stdio"]
config = { provideFormatter = true }
-environment = { "ENV1" = "value1", "ENV2" = "value2" }
+environment = { "ENV1" = "value1", "ENV2" = "value2" }
[language-server.efm-lsp-prettier]
-command = "efm-langserver"
+command = "efm-langserver"
[language-server.efm-lsp-prettier.config]
documentFormatting = true
-languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] }
+languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] }
These are the available options for a language server.
Key Description argsA list of arguments to pass to the language server binary configLSP initialization options timeoutThe maximum time a request to the language server may take, in seconds. Defaults to 20 environmentAny environment variables that will be used when starting the language server { "KEY1" = "Value1", "KEY2" = "Value2" } environmentAny environment variables that will be used when starting the language server { "KEY1" = "Value1", "KEY2" = "Value2" } required-root-patternsA list of glob patterns to look for in the working directory. The language server is started if at least one of them is found.
A format sub-table within config can be used to pass extra formatting options to
Document Formatting Requests.
For example, with typescript:
[language-server.typescript-language-server]
-# pass format options according to https://github.com/typescript-language-server/typescript-language-server#workspacedidchangeconfiguration omitting the "[language].format." prefix.
-config = { format = { "semicolons" = "insert", "insertSpaceBeforeFunctionParenthesis" = true } }
+# pass format options according to https://github.com/typescript-language-server/typescript-language-server#workspacedidchangeconfiguration omitting the "[language].format." prefix.
+config = { format = { "semicolons" = "insert", "insertSpaceBeforeFunctionParenthesis" = true } }
Configuring Language Servers for a language
The language-servers attribute in a language tells helix which language servers are used for this language.
@@ -2247,13 +2345,13 @@ it's often useful to only enable/disable certain language-server features for th
so everything else should be handled by the typescript-language-server (which is configured by default).
The language configuration for typescript could look like this:
[[language]]
-name = "typescript"
-language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ]
+name = "typescript"
+language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ]
or equivalent:
[[language]]
-name = "typescript"
-language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ]
+name = "typescript"
+language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ]
Each requested LSP feature is prioritized in the order of the language-servers array.
For example, the first goto-definition supported language server (in this case typescript-language-server) will be taken for the relevant LSP request (command goto_definition).
@@ -2284,8 +2382,8 @@ If a language server itself doesn't support a feature, the next language server
The source for a language's tree-sitter grammar is specified in a [[grammar]]
section in languages.toml. For example:
[[grammar]]
-name = "mylang"
-source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" }
+name = "mylang"
+source = { git = "https://github.com/example/mylang", rev = "a250c4582510ff34767ec3b7dcdd3c24e8c8aa68" }
Grammar configuration takes these keys:
Key Description You may use a top-level use-grammars key to control which grammars are
fetched and built when using hx --grammar fetch and hx --grammar build.
# Note: this key must come **before** the [[language]] and [[grammar]] sections
-use-grammars = { only = [ "rust", "c", "cpp" ] }
+use-grammars = { only = [ "rust", "c", "cpp" ] }
# or
-use-grammars = { except = [ "yaml", "json" ] }
+use-grammars = { except = [ "yaml", "json" ] }
When omitted, all grammars are fetched and built.
Guides
@@ -2393,7 +2491,7 @@ for example).
comment.around
-Example query files can be found in the helix GitHub repository.
+Example query files can be found in the helix GitHub repository.
Queries for textobject based navigation
Tree-sitter based navigation in Helix is done using captures in the
following order:
@@ -2416,6 +2514,14 @@ the capture.
Note that it matters where these added indents begin. For example,
multiple indent level increases that start on the same line only increase
the total indent level by 1. See Capture types.
+By default, Helix uses the hybrid indentation heuristic. This means that
+indent queries are not used to compute the expected absolute indentation of a
+line but rather the expected difference in indentation between the new and an
+already existing line. This difference is then added to the actual indentation
+of the already existing line. Since this makes errors in the indent queries
+harder to find, it is recommended to disable it when testing via
+:set indent-heuristic tree-sitter. The rest of this guide assumes that
+the tree-sitter heuristic is used.
Indent queries
When Helix is inserting a new line through o, O, or <ret>, to determine
the indent level for the new line, the query in indents.scm is run on the
@@ -2510,7 +2616,7 @@ actually have been extended).
// 3x @outdent
}
((block) @indent)
-["}" ")"] @outdent
+["}" ")"] @outdent
Note how on the second line, we have two blocks begin on the same line. In this case, since both captures occur on the same line, they are combined and only @@ -2550,7 +2656,7 @@ whitespace-sensitive.
the cursor on a line feed ends up being the entire inside of the class. Because of this, it will miss the entire function node and its indent capture, leading to an indent level one too small. -To address this case, @extend tells helix to "extend" the captured node's span
+
To address this case, @extend tells helix to "extend" the captured node's span
to the line feed and every consecutive line that has a greater indent level than
the line of the node.
(parenthesized_expression) @indent
@@ -2658,7 +2764,7 @@ similar to how #set! declarations work:
)
The number of arguments depends on the predicate that's used.
-Each argument is either a capture (@name) or a string ("some string").
+Each argument is either a capture (@name) or a string ("some string").
The following predicates are supported by tree-sitter:
#any-of?/#not-any-of?:
+The first argument (a capture) must/must not be one of the other arguments
+(strings).
Additionally, we support some custom predicates for indent queries:
#![allow(unused)] fn main() { fn aha() { // โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ - let take = "on me"; // โโโโโโโโโโโโโโโโฎ scope: โ - let take = "me on"; // โโ "tail" โโ (block) @indent + let take = "on me"; // โโโโโโโโโโโโโโโโฎ scope: โ + let take = "me on"; // โโ "tail" โโ (block) @indent let ill = be_gone_days(1 || 2); // โ โ -} // โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโดโ "}" @outdent - // scope: "all" +} // โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโดโ "}" @outdent + // scope: "all" }
We can write the following query with the #set! declaration:
((block) @indent
- (#set! "scope" "tail"))
-("}" @outdent
- (#set! "scope" "all"))
+ (#set! "scope" "tail"))
+("}" @outdent
+ (#set! "scope" "all"))
As we can see, the "tail" scope covers the node, except for the first line. +
As we can see, the "tail" scope covers the node, except for the first line.
Everything up to and including the closing brace gets an indent level of 1.
-Then, on the closing brace, we encounter an outdent with a scope of "all", which
+Then, on the closing brace, we encounter an outdent with a scope of "all", which
means the first line is included, and the indent level is cancelled out on this
line. (Note these scopes are the defaults for @indent and @outdentโthey are
written explicitly for demonstration.)
#any-of? (standard):
+The first argument (a capture) must be one of the other arguments (strings).
Helix uses rainbows.scm tree-sitter query files to provide rainbow bracket
@@ -2805,7 +2920,7 @@ language itself. These queries will go into a
runtime/queries/tsq/rainbows.scm file in the repository root.
First we'll add the @rainbow.bracket captures. TSQ only has parentheses and
square brackets:
["(" ")" "[" "]"] @rainbow.bracket
+["(" ")" "[" "]"] @rainbow.bracket
The ordering of the nodes within the alternation (square brackets) is not
taken into consideration.
@@ -2816,7 +2931,7 @@ names of rules in the grammar. Brackets are usually written in tree-sitter
grammars as literal strings, for example:
{
// ...
- arguments: seq("(", repeat($.argument), ")"),
+ arguments: seq("(", repeat($.argument), ")"),
// ...
}
@@ -2863,7 +2978,7 @@ indirect descendants of some node captured with @rainbow.scope.
If we want to highlight the <, > and </ nodes with rainbow colors, we
capture them as @rainbow.bracket:
["<" ">" "</"] @rainbow.bracket
+["<" ">" "</"] @rainbow.bracket
And we capture (element) as @rainbow.scope because (element) nodes nest
within each other: they increment the nesting level and switch to the next
--
cgit v1.2.3-70-g09d2