<buttonid="sidebar-toggle"class="icon-button"type="button"title="Toggle Table of Contents"aria-label="Toggle Table of Contents"aria-controls="sidebar">
<ahref="print.html"title="Print this book"aria-label="Print this book">
<iid="print-button"class="fa fa-print"></i>
</a>
</div>
</div>
<divid="search-wrapper"class="hidden">
<formid="searchbar-outer"class="searchbar-outer">
<inputtype="search"name="search"id="searchbar"name="searchbar"placeholder="Search this book ..."aria-controls="searchresults-outer"aria-describedby="searchresults-header">
<p>(Currently not fully documented, see the <ahref="./keymap.html">keymappings</a> list for more.)</p>
<p>See <ahref="https://github.com/helix-editor/helix/blob/master/runtime/tutor.txt">tutor.txt</a> (accessible via <code>hx --tutor</code> or <code>:tutor</code>) for a vimtutor-like introduction.</p>
<p>Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with <code>"</code> being used to select a register:</p>
<ul>
<li><code>"ay</code> - Yank the current selection to register <code>a</code>.</li>
<li><code>"op</code> - Paste the text in register <code>o</code> after the selection.</li>
</ul>
<p>If there is a selected register before invoking a change or delete command, the selection will be stored in the register and the action will be carried out:</p>
<ul>
<li><code>"hc</code> - Store the selection in register <code>h</code> and then change it (delete and enter insert mode).</li>
<li><code>"md</code> - Store the selection in register <code>m</code> and delete it.</li>
<p>There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the <ahref="keymap.html#space-mode">keymap</a> for the specifics.
The black hole register works as a no-op register, meaning no data will be written to / read from it.</p>
<p>NOTE: <code>f</code>, <code>c</code>, etc need a tree-sitter grammar active for the current
document and a special tree-sitter query file to work properly. <ahref="./lang-support.html">Only
some grammars</a> currently have the query file implemented.
Contributions are welcome!</p>
</blockquote>
<h2id="tree-sitter-textobject-based-navigation"><aclass="header"href="#tree-sitter-textobject-based-navigation">Tree-sitter Textobject Based Navigation</a></h2>
<p>Navigating between functions, classes, parameters, etc is made
possible by leveraging tree-sitter and textobjects queries. For
example to move to the next function use <code>]f</code>, to move to previous
<tr><td><code>G</code></td><td>Go to line number <code><n></code></td><td><code>goto_line</code></td></tr>
<tr><td><code>Alt-.</code></td><td>Repeat last motion (<code>f</code>, <code>t</code> or <code>m</code>)</td><td><code>repeat_last_motion</code></td></tr>
<tr><td><code>Home</code></td><td>Move to the start of the line</td><td><code>goto_line_start</code></td></tr>
<tr><td><code>End</code></td><td>Move to the end of the line</td><td><code>goto_line_end</code></td></tr>
<tr><td><code>Alt-d</code></td><td>Delete selection, without yanking</td><td><code>delete_selection_noyank</code></td></tr>
<tr><td><code>c</code></td><td>Change selection (delete and enter insert mode)</td><td><code>change_selection</code></td></tr>
<tr><td><code>Alt-c</code></td><td>Change selection (delete and enter insert mode, without yanking)</td><td><code>change_selection_noyank</code></td></tr>
<tr><td><code>Ctrl-a</code></td><td>Increment object (number) under cursor</td><td><code>increment</code></td></tr>
<tr><td><code>Ctrl-x</code></td><td>Decrement object (number) under cursor</td><td><code>decrement</code></td></tr>
<tr><td><code>Q</code></td><td>Start/stop macro recording to the selected register (experimental)</td><td><code>record_macro</code></td></tr>
<tr><td><code>q</code></td><td>Play back a recorded macro from the selected register (experimental)</td><td><code>replay_macro</code></td></tr>
<tr><td><code>|</code></td><td>Pipe each selection through shell command, replacing with output</td><td><code>shell_pipe</code></td></tr>
<tr><td><code>Alt-|</code></td><td>Pipe each selection into shell command, ignoring output</td><td><code>shell_pipe_to</code></td></tr>
<tr><td><code>!</code></td><td>Run shell command, inserting output before each selection</td><td><code>shell_insert_output</code></td></tr>
<tr><td><code>Alt-!</code></td><td>Run shell command, appending output after each selection</td><td><code>shell_append_output</code></td></tr>
<tr><td><code>$</code></td><td>Pipe each selection into shell command, keep selections where command returned 0</td><td><code>shell_keep_pipe</code></td></tr>
<tr><td><code>K</code></td><td>Keep selections matching the regex</td><td><code>keep_selections</code></td></tr>
<tr><td><code>Alt-K</code></td><td>Remove selections matching the regex</td><td><code>remove_selections</code></td></tr>
<tr><td><code>Ctrl-c</code></td><td>Comment/uncomment the selections</td><td><code>toggle_comments</code></td></tr>
<tr><td><code>Alt-k</code>, <code>Alt-up</code></td><td>Expand selection to parent syntax node (<strong>TS</strong>)</td><td><code>expand_selection</code></td></tr>
<tr><td><code>Alt-j</code>, <code>Alt-down</code></td><td>Shrink syntax tree object selection (<strong>TS</strong>)</td><td><code>shrink_selection</code></td></tr>
<tr><td><code>Alt-h</code>, <code>Alt-left</code></td><td>Select previous sibling node in syntax tree (<strong>TS</strong>)</td><td><code>select_prev_sibling</code></td></tr>
<tr><td><code>Alt-l</code>, <code>Alt-right</code></td><td>Select next sibling node in syntax tree (<strong>TS</strong>)</td><td><code>select_next_sibling</code></td></tr>
<tr><td><code>s</code><code><char></code></td><td>Surround current selection with <code><char></code></td><td><code>surround_add</code></td></tr>
<tr><td><code>r</code><code><from><to></code></td><td>Replace surround character <code><from></code> with <code><to></code></td><td><code>surround_replace</code></td></tr>
<tr><td><code>d</code><code><char></code></td><td>Delete surround character <code><char></code></td><td><code>surround_delete</code></td></tr>
<tr><td><code>a</code><code><object></code></td><td>Select around textobject</td><td><code>select_textobject_around</code></td></tr>
<tr><td><code>k</code></td><td>Show documentation for item under cursor in a <ahref="keymap.html#popup">popup</a> (<strong>LSP</strong>)</td><td><code>hover</code></td></tr>
<tr><td><code>s</code></td><td>Open document symbol picker (<strong>LSP</strong>)</td><td><code>symbol_picker</code></td></tr>
<tr><td><code>S</code></td><td>Open workspace symbol picker (<strong>LSP</strong>)</td><td><code>workspace_symbol_picker</code></td></tr>
<tr><td><code>r</code></td><td>Rename symbol (<strong>LSP</strong>)</td><td><code>rename_symbol</code></td></tr>
<tr><td><code>:quit</code>, <code>:q</code></td><td>Close the current view.</td></tr>
<tr><td><code>:quit!</code>, <code>:q!</code></td><td>Close the current view forcefully (ignoring unsaved changes).</td></tr>
<tr><td><code>:open</code>, <code>:o</code></td><td>Open a file from disk into the current view.</td></tr>
<tr><td><code>:buffer-close</code>, <code>:bc</code>, <code>:bclose</code></td><td>Close the current buffer.</td></tr>
<tr><td><code>:buffer-close!</code>, <code>:bc!</code>, <code>:bclose!</code></td><td>Close the current buffer forcefully (ignoring unsaved changes).</td></tr>
<tr><td><code>:buffer-close-others</code>, <code>:bco</code>, <code>:bcloseother</code></td><td>Close all buffers but the currently focused one.</td></tr>
<tr><td><code>:buffer-close-others!</code>, <code>:bco!</code>, <code>:bcloseother!</code></td><td>Close all buffers but the currently focused one.</td></tr>
<tr><td><code>:buffer-close-all</code>, <code>:bca</code>, <code>:bcloseall</code></td><td>Close all buffers, without quiting.</td></tr>
<tr><td><code>:buffer-close-all!</code>, <code>:bca!</code>, <code>:bcloseall!</code></td><td>Close all buffers forcefully (ignoring unsaved changes), without quiting.</td></tr>
<tr><td><code>:write</code>, <code>:w</code></td><td>Write changes to disk. Accepts an optional path (:write some/path.txt)</td></tr>
<tr><td><code>:new</code>, <code>:n</code></td><td>Create a new scratch buffer.</td></tr>
<tr><td><code>:format</code>, <code>:fmt</code></td><td>Format the file using the LSP formatter.</td></tr>
<tr><td><code>:indent-style</code></td><td>Set the indentation style for editing. ('t' for tabs or 1-8 for number of spaces.)</td></tr>
<tr><td><code>:line-ending</code></td><td>Set the document's default line ending. Options: crlf, lf, cr, ff, nel.</td></tr>
<tr><td><code>:earlier</code>, <code>:ear</code></td><td>Jump back to an earlier point in edit history. Accepts a number of steps or a time span.</td></tr>
<tr><td><code>:later</code>, <code>:lat</code></td><td>Jump to a later point in edit history. Accepts a number of steps or a time span.</td></tr>
<tr><td><code>:write-quit</code>, <code>:wq</code>, <code>:x</code></td><td>Write changes to disk and close the current view. Accepts an optional path (:wq some/path.txt)</td></tr>
<tr><td><code>:write-quit!</code>, <code>:wq!</code>, <code>:x!</code></td><td>Write changes to disk and close the current view forcefully. Accepts an optional path (:wq! some/path.txt)</td></tr>
<tr><td><code>:write-all</code>, <code>:wa</code></td><td>Write changes from all views to disk.</td></tr>
<tr><td><code>:write-quit-all</code>, <code>:wqa</code>, <code>:xa</code></td><td>Write changes from all views to disk and close all views.</td></tr>
<tr><td><code>:write-quit-all!</code>, <code>:wqa!</code>, <code>:xa!</code></td><td>Write changes from all views to disk and close all views forcefully (ignoring unsaved changes).</td></tr>
<tr><td><code>:quit-all</code>, <code>:qa</code></td><td>Close all views.</td></tr>
<tr><td><code>:quit-all!</code>, <code>:qa!</code></td><td>Close all views forcefully (ignoring unsaved changes).</td></tr>
<tr><td><code>:cquit</code>, <code>:cq</code></td><td>Quit with exit code (default 1). Accepts an optional integer exit code (:cq 2).</td></tr>
<tr><td><code>:cquit!</code>, <code>:cq!</code></td><td>Quit with exit code (default 1) forcefully (ignoring unsaved changes). Accepts an optional integer exit code (:cq! 2).</td></tr>
<tr><td><code>:theme</code></td><td>Change the editor theme.</td></tr>
<tr><td><code>:clipboard-yank</code></td><td>Yank main selection into system clipboard.</td></tr>
<tr><td><code>:clipboard-yank-join</code></td><td>Yank joined selections into system clipboard. A separator can be provided as first argument. Default value is newline.</td></tr>
<tr><td><code>:primary-clipboard-yank</code></td><td>Yank main selection into system primary clipboard.</td></tr>
<tr><td><code>:primary-clipboard-yank-join</code></td><td>Yank joined selections into system primary clipboard. A separator can be provided as first argument. Default value is newline.</td></tr>
<tr><td><code>:clipboard-paste-after</code></td><td>Paste system clipboard after selections.</td></tr>
<tr><td><code>:clipboard-paste-before</code></td><td>Paste system clipboard before selections.</td></tr>
<tr><td><code>:clipboard-paste-replace</code></td><td>Replace selections with content of system clipboard.</td></tr>
<tr><td><code>:primary-clipboard-paste-after</code></td><td>Paste primary clipboard after selections.</td></tr>
<tr><td><code>:primary-clipboard-paste-before</code></td><td>Paste primary clipboard before selections.</td></tr>
<tr><td><code>:primary-clipboard-paste-replace</code></td><td>Replace selections with content of system primary clipboard.</td></tr>
<tr><td><code>:show-clipboard-provider</code></td><td>Show clipboard provider name in status bar.</td></tr>
<tr><td><code>:change-current-directory</code>, <code>:cd</code></td><td>Change the current working directory.</td></tr>
<tr><td><code>:show-directory</code>, <code>:pwd</code></td><td>Show the current working directory.</td></tr>
<tr><td><code>:encoding</code></td><td>Set encoding based on <code>https://encoding.spec.whatwg.org</code></td></tr>
<tr><td><code>:reload</code></td><td>Discard changes and reload from the source file.</td></tr>
<tr><td><code>:tree-sitter-scopes</code></td><td>Display tree sitter scopes, primarily for theming and development.</td></tr>
<tr><td><code>:debug-start</code>, <code>:dbg</code></td><td>Start a debug session from a given template with given parameters.</td></tr>
<tr><td><code>:debug-remote</code>, <code>:dbg-tcp</code></td><td>Connect to a debug adapter by TCP address and start a debugging session from a given template with given parameters.</td></tr>
<tr><td><code>:debug-eval</code></td><td>Evaluate expression in current debug context.</td></tr>
<tr><td><code>:vsplit</code>, <code>:vs</code></td><td>Open the file in a vertical split.</td></tr>
<tr><td><code>:tutor</code></td><td>Open the tutorial.</td></tr>
<tr><td><code>:goto</code>, <code>:g</code></td><td>Go to line number.</td></tr>
<tr><td><code>:set-option</code>, <code>:set</code></td><td>Set a config option at runtime</td></tr>
<tr><td><code>:sort</code></td><td>Sort ranges in selection.</td></tr>
<tr><td><code>:rsort</code></td><td>Sort ranges in selection in reverse order.</td></tr>
<tr><td><code>:tree-sitter-subtree</code>, <code>:ts-subtree</code></td><td>Display tree sitter subtree under cursor, primarily for debugging queries.</td></tr>
<tr><td><code>scroll-lines</code></td><td>Number of lines to scroll per scroll wheel step.</td><td><code>3</code></td></tr>
<tr><td><code>shell</code></td><td>Shell to use when running external commands.</td><td>Unix: <code>["sh", "-c"]</code><br/>Windows: <code>["cmd", "/C"]</code></td></tr>
<tr><td><code>line-number</code></td><td>Line number display: <code>absolute</code> simply shows each line's number, while <code>relative</code> shows the distance from the current line. When unfocused or in insert mode, <code>relative</code> will still show absolute line numbers.</td><td><code>absolute</code></td></tr>
<tr><td><code>auto-completion</code></td><td>Enable automatic pop up of auto-completion.</td><td><code>true</code></td></tr>
<tr><td><code>idle-timeout</code></td><td>Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant.</td><td><code>400</code></td></tr>
<tr><td><code>completion-trigger-len</code></td><td>The min-length of word under cursor to trigger autocompletion</td><td><code>2</code></td></tr>
<tr><td><code>auto-info</code></td><td>Whether to display infoboxes</td><td><code>true</code></td></tr>
<tr><td><code>true-color</code></td><td>Set to <code>true</code> to override automatic detection of terminal truecolor support in the event of a false negative.</td><td><code>false</code></td></tr>
<tr><td><code>git-global</code></td><td>Enables reading global .gitignore, whose path is specified in git's config: <code>core.excludefile</code> option.</td><td>true</td></tr>
<p>To use a theme add <code>theme = "<name>"</code> to your <ahref="./configuration.html"><code>config.toml</code></a> at the very top of the file before the first section or select it during runtime using <code>:theme <name></code>.</p>
<h2id="creating-a-theme"><aclass="header"href="#creating-a-theme">Creating a theme</a></h2>
<p>Create a file with the name of your theme as file name (i.e <code>mytheme.toml</code>) and place it in your <code>themes</code> directory (i.e <code>~/.config/helix/themes</code>). The directory might have to be created beforehand.</p>
<p>The names "default" and "base16_default" are reserved for the builtin themes and cannot be overridden by user defined themes.</p>
<p>The default theme.toml can be found <ahref="https://github.com/helix-editor/helix/blob/master/theme.toml">here</a>, and user submitted themes <ahref="https://github.com/helix-editor/helix/blob/master/runtime/themes">here</a>. </p>
<p>Each line in the theme file is specified as below:</p>
<p>where <code>key</code> represents what you want to style, <code>fg</code> specifies the foreground color, <code>bg</code> the background color, and <code>modifiers</code> is a list of style modifiers. <code>bg</code> and <code>modifiers</code> can be omitted to defer to the defaults.</p>
<p>if the key contains a dot <code>'.'</code>, it must be quoted to prevent it being parsed as a <ahref="https://toml.io/en/v1.0.0#keys">dotted key</a>.</p>
<p>These keys match <ahref="https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme">tree-sitter scopes</a>.</p>
<p>For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight <code>function.builtin.static</code> would match the key <code>function.builtin</code> rather than <code>function</code>.</p>
<p>We use a similar set of scopes as
<ahref="https://www.sublimetext.com/docs/scope_naming.html">SublimeText</a>. See also
<p>Keys can be disabled by binding them to the <code>no_op</code> command.</p>
<p>Commands can be found at <ahref="https://docs.helix-editor.com/keymap.html">Keymap</a> Commands.</p>
<blockquote>
<p>Commands can also be found in the source code at <ahref="https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs"><code>helix-term/src/commands.rs</code></a> at the invocation of <code>static_commands!</code> macro and the <code>TypableCommandList</code>.</p>
<p>Language-specific settings and settings for particular language servers can be configured in a <code>languages.toml</code> file placed in your <ahref="./configuration.html">configuration directory</a>. Helix actually uses two <code>languages.toml</code> files, the <ahref="https://github.com/helix-editor/helix/blob/master/languages.toml">first one</a> is in the main helix repository; it contains the default settings for each language and is included in the helix binary at compile time. Users who want to see the available settings and options can either reference the helix repo's <code>languages.toml</code> file, or consult the table in the <ahref="./guides/adding_languages.html">adding languages</a> section.</p>
<p>Changes made to the <code>languages.toml</code> file in a user's <ahref="./configuration.html">configuration directory</a> are merged with helix's defaults on start-up, such that a user's settings will take precedence over defaults in the event of a collision. For example, the default <code>languages.toml</code> sets rust's <code>auto-format</code> to <code>true</code>. If a user wants to disable auto-format, they can change the <code>languages.toml</code> in their <ahref="./configuration.html">configuration directory</a> to make the rust entry read like the example below; the new key/value pair <code>auto-format = false</code> will override the default when the two sets of settings are merged on start-up:</p>
<pre><codeclass="language-toml"># in <config_dir>/helix/languages.toml
<tr><td><code>name</code></td><td>The name of the language</td></tr>
<tr><td><code>scope</code></td><td>A string like <code>source.js</code> that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually <code>source.<name></code> or <code>text.<name></code> in case of markup languages</td></tr>
<tr><td><code>injection-regex</code></td><td>regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential <ahref="https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection">language injection</a> site.</td></tr>
<tr><td><code>file-types</code></td><td>The filetypes of the language, for example <code>["yml", "yaml"]</code>. Extensions and full file names are supported.</td></tr>
<tr><td><code>shebangs</code></td><td>The interpreters from the shebang line, for example <code>["sh", "bash"]</code></td></tr>
<tr><td><code>roots</code></td><td>A set of marker files to look for when trying to find the workspace root. For example <code>Cargo.lock</code>, <code>yarn.lock</code></td></tr>
<tr><td><code>auto-format</code></td><td>Whether to autoformat this language when saving</td></tr>
<tr><td><code>diagnostic-severity</code></td><td>Minimal severity of diagnostic for it to be displayed. (Allowed values: <code>Error</code>, <code>Warning</code>, <code>Info</code>, <code>Hint</code>)</td></tr>
<tr><td><code>comment-token</code></td><td>The token to use as a comment-token</td></tr>
<tr><td><code>indent</code></td><td>The indent to use. Has sub keys <code>tab-width</code> and <code>unit</code></td></tr>
<tr><td><code>config</code></td><td>Language server configuration</td></tr>
<tr><td><code>grammar</code></td><td>The tree-sitter grammar to use (defaults to the value of <code>name</code>)</td></tr>
<tr><td><code>git</code></td><td>A git remote URL from which the grammar should be cloned</td></tr>
<tr><td><code>rev</code></td><td>The revision (commit hash or tag) which should be fetched</td></tr>
<tr><td><code>subpath</code></td><td>A path within the grammar directory which should be built. Some grammar repositories host multiple grammars (for example <code>tree-sitter-typescript</code> and <code>tree-sitter-ocaml</code>) in subdirectories. This key is used to point <code>hx --grammar build</code> to the correct path for compilation. When omitted, the root of repository is used</td></tr>
</tbody></table>
<p>Or a <code>path</code> key with an absolute path to a locally available grammar directory.</p>
<p>If you get errors when running after switching branches, you may have to update the tree-sitter grammars. Run <code>hx --grammar fetch</code> to fetch the grammars and <code>hx --grammar build</code> to build any out-of-date grammars.</p>
</li>
<li>
<p>If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in <code>runtime/grammar/<name>.so</code></p>
</li>
<li>
<p>The indents query is <code>indents.toml</code>, <em>not</em><code>indents.scm</code>. See <ahref="https://github.com/helix-editor/helix/issues/114">this</a> issue for more information.</p>
<p>Textobjects that are language specific (<ahref="guides/../usage.html#textobjects">like functions, classes, etc</a>)
require an accompanying tree-sitter grammar and a <code>textobjects.scm</code> query file
to work properly. Tree-sitter allows us to query the source code syntax tree
and capture specific parts of it. The queries are written in a lisp dialect.
More information on how to write queries can be found in the <ahref="https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax">official tree-sitter
documentation</a>.</p>
<p>Query files should be placed in <code>runtime/queries/{language}/textobjects.scm</code>
when contributing. Note that to test the query files locally you should put
them under your local runtime directory (<code>~/.config/helix/runtime</code> on Linux
for example).</p>
<p>The following <ahref="https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes">captures</a> are recognized:</p>
<p><ahref="https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=">Example query files</a> can be found in the helix GitHub repository.</p>
<h2id="queries-for-textobject-based-navigation"><aclass="header"href="#queries-for-textobject-based-navigation">Queries for Textobject Based Navigation</a></h2>
<p><ahref="guides/../usage.html#tree-sitter-textobject-based-navigation">Tree-sitter based navigation</a> is done using captures in the
following order:</p>
<ul>
<li><code>object.movement</code></li>
<li><code>object.around</code></li>
<li><code>object.inside</code></li>
</ul>
<p>For example if a <code>function.around</code> capture has been already defined for a language
in it's <code>textobjects.scm</code> file, function navigation should also work automatically.
<code>function.movement</code> should be defined only if the node captured by <code>function.around</code>
