Rewrite and refactor all documentation (#5534)
* Rewrite and refactor all documentation * Rewrite and refactor the guides * update runtime directory instructions for windows * Update the Ubuntu 3rd party repo section with 22.10 * Merge from upstream * Rewrite and refactor all documentation * Apply suggestions from code review Apply the suggestions that can be committed from the GitHub web interface. Co-authored-by: Michael Davis <mcarsondavis@gmail.com> * Add Windows themes folder Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com> * Apply the rest of the suggestions from the code review * Revert "Apply the rest of the suggestions from the code review" This reverts commit 498be1b7a1aec3ff567b95130148628beeef9b77. * Revert "Merge branch 'rewrite-and-refactor-all-documentation' of github.com:David-Else/helix into rewrite-and-refactor-all-documentation" This reverts commit 7c8404248ffef73b80b9051d5a4359c5bcfa5d1a, reversing changes made to d932969cfc9fadda12a74cc01665919dee7152fb. * Apply code review suggestions * Changes after re-reading all documents * Missed a full stop * Code review suggestions and remove macOS and Windows specific sections * Add OpenBSD to heading * Add back macOS and Windows sections and further simplify and improve * Change wording to nightly * Remove README installation section and turn into a link * Simplify building from source and follow code review suggestions * Code review revisions * Fix copy paste mistake * Apply the latest code review suggestions * More small code review items * Change minor modes for code review * Fix link and typos * Add note that you need a c++ compiler to install the tree-sitter grammars * Add pacman example * Make sure all headings are lower case * Revert to the original passage adding a reference to Windows that was missing * Update book/src/guides/adding_languages.md Fix grammar typo Co-authored-by: Michael Davis <mcarsondavis@gmail.com> * Update book/src/install.md Fix tree sitter typo Co-authored-by: Michael Davis <mcarsondavis@gmail.com> * Remove TOC links to main heading --------- Co-authored-by: CptPotato <3957610+CptPotato@users.noreply.github.com> Co-authored-by: Michael Davis <mcarsondavis@gmail.com> Co-authored-by: digidoor <37601466+digidoor@users.noreply.github.com>
This commit is contained in:
David Else
GitHub
parent
5ebe1014ac
commit
707457c632
15 changed files with 469 additions and 475 deletions
84
README.md
84
README.md
|
|
@ -45,92 +45,10 @@ Note: Only certain languages have indentation definitions at the moment. Check
|
|||
|
||||
# Installation
|
||||
|
||||
Packages are available for various distributions (see [Installation docs](https://docs.helix-editor.com/install.html)).
|
||||
|
||||
If you would like to build from source:
|
||||
|
||||
```shell
|
||||
git clone https://github.com/helix-editor/helix
|
||||
cd helix
|
||||
cargo install --locked --path helix-term
|
||||
```
|
||||
|
||||
This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.
|
||||
|
||||
Helix needs its runtime files so make sure to copy/symlink the `runtime/` directory into the
|
||||
config directory (for example `~/.config/helix/runtime` on Linux/macOS, or `%AppData%/helix/runtime` on Windows).
|
||||
|
||||
| OS | Command |
|
||||
| -------------------- | ------------------------------------------------ |
|
||||
| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` |
|
||||
| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |
|
||||
| Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` |
|
||||
|
||||
Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires
|
||||
elevated privileges - i.e. PowerShell or Cmd must be run as administrator.
|
||||
|
||||
**PowerShell:**
|
||||
|
||||
```powershell
|
||||
New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
|
||||
```
|
||||
Note: "runtime" must be absolute path to the runtime directory.
|
||||
|
||||
**Cmd:**
|
||||
|
||||
```cmd
|
||||
cd %appdata%\helix
|
||||
mklink /D runtime "<helix-repo>\runtime"
|
||||
```
|
||||
|
||||
The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.
|
||||
|
||||
> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --locked --path helix-term`,
|
||||
> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`.
|
||||
|
||||
If you plan on keeping the repo locally, an alternative to copying/symlinking
|
||||
runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime`
|
||||
(`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory).
|
||||
|
||||
Packages already solve this for you by wrapping the `hx` binary with a wrapper
|
||||
that sets the variable to the install dir.
|
||||
|
||||
> NOTE: running via cargo also doesn't require setting explicit `HELIX_RUNTIME` path, it will automatically
|
||||
> detect the `runtime` directory in the project root.
|
||||
|
||||
If you want to customize your `languages.toml` config,
|
||||
tree-sitter grammars may be manually fetched and built with `hx --grammar fetch` and `hx --grammar build`.
|
||||
|
||||
In order to use LSP features like auto-complete, you will need to
|
||||
[install the appropriate Language Server](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
|
||||
for a language.
|
||||
[Installation documentation](https://docs.helix-editor.com/install.html).
|
||||
|
||||
[](https://repology.org/project/helix/versions)
|
||||
|
||||
## Adding Helix to your desktop environment
|
||||
|
||||
If installing from source, to use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder:
|
||||
|
||||
```bash
|
||||
cp contrib/Helix.desktop ~/.local/share/applications
|
||||
cp contrib/helix.png ~/.local/share/icons
|
||||
```
|
||||
|
||||
To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
## macOS
|
||||
|
||||
Helix can be installed on macOS through homebrew:
|
||||
|
||||
```
|
||||
brew install helix
|
||||
```
|
||||
|
||||
# Contributing
|
||||
|
||||
Contributing guidelines can be found [here](./docs/CONTRIBUTING.md).
|
||||
|
|
|
|||
|
|
@ -6,13 +6,13 @@
|
|||
- [Usage](./usage.md)
|
||||
- [Keymap](./keymap.md)
|
||||
- [Commands](./commands.md)
|
||||
- [Language Support](./lang-support.md)
|
||||
- [Language support](./lang-support.md)
|
||||
- [Migrating from Vim](./from-vim.md)
|
||||
- [Configuration](./configuration.md)
|
||||
- [Themes](./themes.md)
|
||||
- [Key Remapping](./remapping.md)
|
||||
- [Key remapping](./remapping.md)
|
||||
- [Languages](./languages.md)
|
||||
- [Guides](./guides/README.md)
|
||||
- [Adding Languages](./guides/adding_languages.md)
|
||||
- [Adding Textobject Queries](./guides/textobject.md)
|
||||
- [Adding Indent Queries](./guides/indent.md)
|
||||
- [Adding languages](./guides/adding_languages.md)
|
||||
- [Adding textobject queries](./guides/textobject.md)
|
||||
- [Adding indent queries](./guides/indent.md)
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
# Commands
|
||||
|
||||
Command mode can be activated by pressing `:`, similar to Vim. Built-in commands:
|
||||
Command mode can be activated by pressing `:`. The built-in commands are:
|
||||
|
||||
{{#include ./generated/typable-cmd.md}}
|
||||
|
|
|
|||
|
|
@ -2,10 +2,10 @@
|
|||
|
||||
To override global configuration parameters, create a `config.toml` file located in your config directory:
|
||||
|
||||
* Linux and Mac: `~/.config/helix/config.toml`
|
||||
* Windows: `%AppData%\helix\config.toml`
|
||||
- Linux and Mac: `~/.config/helix/config.toml`
|
||||
- Windows: `%AppData%\helix\config.toml`
|
||||
|
||||
> Hint: You can easily open the config file by typing `:config-open` within Helix normal mode.
|
||||
> 💡 You can easily open the config file by typing `:config-open` within Helix normal mode.
|
||||
|
||||
Example config:
|
||||
|
||||
|
|
@ -25,12 +25,10 @@ select = "underline"
|
|||
hidden = false
|
||||
```
|
||||
|
||||
You may also specify a file to use for configuration with the `-c` or
|
||||
`--config` CLI argument: `hx -c path/to/custom-config.toml`.
|
||||
|
||||
It is also possible to trigger configuration file reloading by sending the `USR1`
|
||||
signal to the helix process, e.g. via `pkill -USR1 hx`. This is only supported
|
||||
on unix operating systems.
|
||||
You can use a custom configuration file by specifying it with the `-c` or
|
||||
`--config` command line argument, for example `hx -c path/to/custom-config.toml`.
|
||||
Additionally, you can reload the configuration file by sending the USR1
|
||||
signal to the Helix process on Unix operating systems, such as by using the command `pkill -USR1 hx`.
|
||||
|
||||
## Editor
|
||||
|
||||
|
|
@ -38,23 +36,23 @@ on unix operating systems.
|
|||
|
||||
| Key | Description | Default |
|
||||
|--|--|---------|
|
||||
| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `5` |
|
||||
| `mouse` | Enable mouse mode. | `true` |
|
||||
| `middle-click-paste` | Middle click paste support. | `true` |
|
||||
| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` |
|
||||
| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
|
||||
| `line-number` | Line 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. | `absolute` |
|
||||
| `cursorline` | Highlight all lines with a cursor. | `false` |
|
||||
| `cursorcolumn` | Highlight all columns with a cursor. | `false` |
|
||||
| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling | `5` |
|
||||
| `mouse` | Enable mouse mode | `true` |
|
||||
| `middle-click-paste` | Middle click paste support | `true` |
|
||||
| `scroll-lines` | Number of lines to scroll per scroll wheel step | `3` |
|
||||
| `shell` | Shell to use when running external commands | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` |
|
||||
| `line-number` | Line 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 | `absolute` |
|
||||
| `cursorline` | Highlight all lines with a cursor | `false` |
|
||||
| `cursorcolumn` | Highlight all columns with a cursor | `false` |
|
||||
| `gutters` | Gutters 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-completion` | Enable automatic pop up of auto-completion. | `true` |
|
||||
| `auto-format` | Enable automatic formatting on save. | `true` |
|
||||
| `auto-save` | Enable automatic saving on focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal. | `false` |
|
||||
| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant. | `400` |
|
||||
| `auto-completion` | Enable automatic pop up of auto-completion | `true` |
|
||||
| `auto-format` | Enable automatic formatting on save | `true` |
|
||||
| `auto-save` | Enable automatic saving on the focus moving away from Helix. Requires [focus event support](https://github.com/helix-editor/helix/wiki/Terminal-Support) from your terminal | `false` |
|
||||
| `idle-timeout` | Time in milliseconds since last keypress before idle timers trigger. Used for autocompletion, set to 0 for instant | `400` |
|
||||
| `completion-trigger-len` | The min-length of word under cursor to trigger autocompletion | `2` |
|
||||
| `auto-info` | Whether to display infoboxes | `true` |
|
||||
| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative. | `false` |
|
||||
| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file. | `[]` |
|
||||
| `auto-info` | Whether to display info boxes | `true` |
|
||||
| `true-color` | Set to `true` to override automatic detection of terminal truecolor support in the event of a false negative | `false` |
|
||||
| `rulers` | List of column positions at which to display the rulers. Can be overridden by language specific `rulers` in `languages.toml` file | `[]` |
|
||||
| `bufferline` | Renders 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) | `never` |
|
||||
| `color-modes` | Whether to color the mode indicator with different colors depending on the mode itself | `false` |
|
||||
|
||||
|
|
@ -125,10 +123,12 @@ The following statusline elements can be configured:
|
|||
|
||||
### `[editor.cursor-shape]` Section
|
||||
|
||||
Defines the shape of cursor in each mode. Note that due to limitations
|
||||
of the terminal environment, only the primary cursor can change shape.
|
||||
Defines the shape of cursor in each mode.
|
||||
Valid values for these options are `block`, `bar`, `underline`, or `hidden`.
|
||||
|
||||
> 💡 Due to limitations of the terminal environment, only the primary cursor can
|
||||
> change shape.
|
||||
|
||||
| Key | Description | Default |
|
||||
| --- | ----------- | ------- |
|
||||
| `normal` | Cursor shape in [normal mode][normal mode] | `block` |
|
||||
|
|
@ -141,25 +141,22 @@ Valid values for these options are `block`, `bar`, `underline`, or `hidden`.
|
|||
|
||||
### `[editor.file-picker]` Section
|
||||
|
||||
Sets options for file picker and global search. All but the last key listed in
|
||||
the default file-picker configuration below are IgnoreOptions: whether hidden
|
||||
files and files listed within ignore files are ignored by (not visible in) the
|
||||
helix file picker and global search. There is also one other key, `max-depth`
|
||||
available, which is not defined by default.
|
||||
Set options for file picker and global search. Ignoring a file means it is
|
||||
not visible in the Helix file picker and global search.
|
||||
|
||||
All git related options are only enabled in a git repository.
|
||||
|
||||
| Key | Description | Default |
|
||||
|--|--|---------|
|
||||
|`hidden` | Enables ignoring hidden files. | true
|
||||
|`hidden` | Enables ignoring hidden files | true
|
||||
|`follow-links` | Follow symlinks instead of ignoring them | true
|
||||
|`deduplicate-links` | Ignore symlinks that point at files already shown in the picker | true
|
||||
|`parents` | Enables reading ignore files from parent directories. | true
|
||||
|`ignore` | Enables reading `.ignore` files. | true
|
||||
|`git-ignore` | Enables reading `.gitignore` files. | true
|
||||
|`git-global` | Enables reading global .gitignore, whose path is specified in git's config: `core.excludefile` option. | true
|
||||
|`git-exclude` | Enables reading `.git/info/exclude` files. | true
|
||||
|`max-depth` | Set with an integer value for maximum depth to recurse. | Defaults to `None`.
|
||||
|`parents` | Enables reading ignore files from parent directories | true
|
||||
|`ignore` | Enables reading `.ignore` files | true
|
||||
|`git-ignore` | Enables reading `.gitignore` files | true
|
||||
|`git-global` | Enables reading global `.gitignore`, whose path is specified in git's config: `core.excludefile` option | true
|
||||
|`git-exclude` | Enables reading `.git/info/exclude` files | true
|
||||
|`max-depth` | Set with an integer value for maximum depth to recurse | Defaults to `None`.
|
||||
|
||||
### `[editor.auto-pairs]` Section
|
||||
|
||||
|
|
@ -211,7 +208,7 @@ Search specific options.
|
|||
|
||||
| Key | Description | Default |
|
||||
|--|--|---------|
|
||||
| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` |
|
||||
| `smart-case` | Enable smart case regex searching (case-insensitive unless pattern contains upper case characters) | `true` |
|
||||
| `wrap-around`| Whether the search should wrap after depleting the matches | `true` |
|
||||
|
||||
### `[editor.whitespace]` Section
|
||||
|
|
@ -220,7 +217,7 @@ Options for rendering whitespace with visible characters. Use `:set whitespace.r
|
|||
|
||||
| Key | Description | Default |
|
||||
|-----|-------------|---------|
|
||||
| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline`. | `"none"` |
|
||||
| `render` | Whether to render whitespace. May either be `"all"` or `"none"`, or a table with sub-keys `space`, `nbsp`, `tab`, and `newline` | `"none"` |
|
||||
| `characters` | Literal characters to use when rendering whitespace. Sub-keys may be any of `tab`, `space`, `nbsp`, `newline` or `tabpad` | See example below |
|
||||
|
||||
Example
|
||||
|
|
@ -248,7 +245,7 @@ Options for rendering vertical indent guides.
|
|||
|
||||
| Key | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `render` | Whether to render indent guides. | `false` |
|
||||
| `render` | Whether to render indent guides | `false` |
|
||||
| `character` | Literal character to use for rendering the indent guide | `│` |
|
||||
| `skip-levels` | Number of indent levels to skip | `0` |
|
||||
|
||||
|
|
@ -273,7 +270,7 @@ 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 sub-sections.
|
||||
specific gutter components as subsections.
|
||||
|
||||
| Key | Description | Default |
|
||||
| --- | --- | --- |
|
||||
|
|
@ -315,13 +312,13 @@ Currently unused
|
|||
|
||||
### `[editor.soft-wrap]` Section
|
||||
|
||||
Options for soft wrapping lines that exceed the view width
|
||||
Options for soft wrapping lines that exceed the view width:
|
||||
|
||||
| Key | Description | Default |
|
||||
| --- | --- | --- |
|
||||
| `enable` | Whether soft wrapping is enabled. | `false` |
|
||||
| `max-wrap` | Maximum free space left at the end of the line. | `20` |
|
||||
| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line. | `40` |
|
||||
| `enable` | Whether soft wrapping is enabled | `false` |
|
||||
| `max-wrap` | Maximum free space left at the end of the line | `20` |
|
||||
| `max-indent-retain` | Maximum indentation to carry over when soft wrapping a line | `40` |
|
||||
| `wrap-indicator` | Text inserted before soft wrapped lines, highlighted with `ui.virtual.wrap` | `↪ ` |
|
||||
|
||||
Example:
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Guides
|
||||
|
||||
This section contains guides for adding new language server configurations,
|
||||
tree-sitter grammars, textobject queries, etc.
|
||||
tree-sitter grammars, textobject queries, and other similar items.
|
||||
|
|
|
|||
|
|
@ -1,45 +1,52 @@
|
|||
# Adding languages
|
||||
# Adding new languages to Helix
|
||||
|
||||
In order to add a new language to Helix, you will need to follow the steps
|
||||
below.
|
||||
|
||||
## Language configuration
|
||||
|
||||
To add a new language, you need to add a `[[language]]` entry to the
|
||||
`languages.toml` (see the [language configuration section]).
|
||||
1. Add a new `[[language]]` entry in the `languages.toml` file and provide the
|
||||
necessary configuration for the new language. For more information on
|
||||
language configuration, refer to the
|
||||
[language configuration section](../languages.md) of the documentation.
|
||||
2. If you are adding a new language or updating an existing language server
|
||||
configuration, run the command `cargo xtask docgen` to update the
|
||||
[Language Support](../lang-support.md) documentation.
|
||||
|
||||
When adding a new language or Language Server configuration for an existing
|
||||
language, run `cargo xtask docgen` to add the new configuration to the
|
||||
[Language Support][lang-support] docs before creating a pull request.
|
||||
When adding a Language Server configuration, be sure to update the
|
||||
[Language Server Wiki][install-lsp-wiki] with installation notes.
|
||||
> 💡 If you are adding a new Language Server configuration, make sure to update
|
||||
> the
|
||||
> [Language Server Wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
|
||||
> with the installation instructions.
|
||||
|
||||
## Grammar configuration
|
||||
|
||||
If a tree-sitter grammar is available for the language, add a new `[[grammar]]`
|
||||
entry to `languages.toml`.
|
||||
|
||||
You may use the `source.path` key rather than `source.git` with an absolute path
|
||||
to a locally available grammar for testing, but switch to `source.git` before
|
||||
submitting a pull request.
|
||||
1. If a tree-sitter grammar is available for the new language, add a new
|
||||
`[[grammar]]` entry to the `languages.toml` file.
|
||||
2. If you are testing the grammar locally, you can use the `source.path` key
|
||||
with an absolute path to the grammar. However, before submitting a pull
|
||||
request, make sure to switch to using `source.git`.
|
||||
|
||||
## Queries
|
||||
|
||||
For a language to have syntax-highlighting and indentation among
|
||||
other things, you have to add queries. Add a directory for your
|
||||
language with the path `runtime/queries/<name>/`. The tree-sitter
|
||||
[website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries)
|
||||
gives more info on how to write queries.
|
||||
1. In order to provide syntax highlighting and indentation for the new language,
|
||||
you will need to add queries.
|
||||
2. Create a new directory for the language with the path
|
||||
`runtime/queries/<name>/`.
|
||||
3. Refer to the
|
||||
[tree-sitter website](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#queries)
|
||||
for more information on writing queries.
|
||||
|
||||
> NOTE: When evaluating queries, the first matching query takes
|
||||
precedence, which is different from other editors like Neovim where
|
||||
the last matching query supersedes the ones before it. See
|
||||
[this issue][neovim-query-precedence] for an example.
|
||||
> 💡 In Helix, the first matching query takes precedence when evaluating
|
||||
> queries, which is different from other editors such as Neovim where the last
|
||||
> matching query supersedes the ones before it. See
|
||||
> [this issue](https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090)
|
||||
> for an example.
|
||||
|
||||
## Common Issues
|
||||
## Common issues
|
||||
|
||||
- If you get errors when running after switching branches, you may have to update the tree-sitter grammars. Run `hx --grammar fetch` to fetch the grammars and `hx --grammar build` to build any out-of-date grammars.
|
||||
|
||||
- If a parser is segfaulting or you want to remove the parser, make sure to remove the compiled parser in `runtime/grammar/<name>.so`
|
||||
|
||||
[language configuration section]: ../languages.md
|
||||
[neovim-query-precedence]: https://github.com/helix-editor/helix/pull/1170#issuecomment-997294090
|
||||
[install-lsp-wiki]: https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers
|
||||
[lang-support]: ../lang-support.md
|
||||
- If you encounter errors when running Helix after switching branches, you may
|
||||
need to update the tree-sitter grammars. Run the command `hx --grammar fetch`
|
||||
to fetch the grammars and `hx --grammar build` to build any out-of-date
|
||||
grammars.
|
||||
- If a parser is causing a segfault, or you want to remove it, make sure to
|
||||
remove the compiled parser located at `runtime/grammars/<name>.so`.
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# Adding Indent Queries
|
||||
# Adding indent queries
|
||||
|
||||
Helix uses tree-sitter to correctly indent new lines. This requires
|
||||
a tree-sitter grammar and an `indent.scm` query file placed in
|
||||
|
|
@ -36,7 +36,7 @@ changed by using a `#set!` declaration anywhere in the pattern:
|
|||
(#set! "scope" "all"))
|
||||
```
|
||||
|
||||
## Capture Types
|
||||
## Capture types
|
||||
|
||||
- `@indent` (default scope `tail`):
|
||||
Increase the indent level by 1. Multiple occurrences in the same line
|
||||
|
|
|
|||
|
|
@ -1,14 +1,14 @@
|
|||
# Adding Textobject Queries
|
||||
# Adding textobject queries
|
||||
|
||||
Textobjects that are language specific ([like functions, classes, etc][textobjects])
|
||||
require an accompanying tree-sitter grammar and a `textobjects.scm` query file
|
||||
Helix supports textobjects that are language specific, such as functions, classes, etc.
|
||||
These textobjects require an accompanying tree-sitter grammar and a `textobjects.scm` 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 [official tree-sitter
|
||||
documentation][tree-sitter-queries].
|
||||
|
||||
Query files should be placed in `runtime/queries/{language}/textobjects.scm`
|
||||
when contributing. Note that to test the query files locally you should put
|
||||
when contributing to Helix. Note that to test the query files locally you should put
|
||||
them under your local runtime directory (`~/.config/helix/runtime` on Linux
|
||||
for example).
|
||||
|
||||
|
|
@ -28,9 +28,9 @@ The following [captures][tree-sitter-captures] are recognized:
|
|||
|
||||
[Example query files][textobject-examples] can be found in the helix GitHub repository.
|
||||
|
||||
## Queries for Textobject Based Navigation
|
||||
## Queries for textobject based navigation
|
||||
|
||||
[Tree-sitter based navigation][textobjects-nav] is done using captures in the
|
||||
Tree-sitter based navigation in Helix is done using captures in the
|
||||
following order:
|
||||
|
||||
- `object.movement`
|
||||
|
|
@ -38,12 +38,10 @@ following order:
|
|||
- `object.inside`
|
||||
|
||||
For example if a `function.around` capture has been already defined for a language
|
||||
in it's `textobjects.scm` file, function navigation should also work automatically.
|
||||
in its `textobjects.scm` file, function navigation should also work automatically.
|
||||
`function.movement` should be defined only if the node captured by `function.around`
|
||||
doesn't make sense in a navigation context.
|
||||
|
||||
[textobjects]: ../usage.md#textobjects
|
||||
[textobjects-nav]: ../usage.md#tree-sitter-textobject-based-navigation
|
||||
[tree-sitter-queries]: https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
|
||||
[tree-sitter-captures]: https://tree-sitter.github.io/tree-sitter/using-parsers#capturing-nodes
|
||||
[textobject-examples]: https://github.com/search?q=repo%3Ahelix-editor%2Fhelix+filename%3Atextobjects.scm&type=Code&ref=advsearch&l=&l=
|
||||
|
|
|
|||
|
|
@ -1,180 +1,223 @@
|
|||
# Installation
|
||||
# Installing Helix
|
||||
|
||||
We provide pre-built binaries on the [GitHub Releases page](https://github.com/helix-editor/helix/releases).
|
||||
<!--toc:start-->
|
||||
- [Pre-built binaries](#pre-built-binaries)
|
||||
- [Linux, macOS, Windows and OpenBSD packaging status](#linux-macos-windows-and-openbsd-packaging-status)
|
||||
- [Linux](#linux)
|
||||
- [Ubuntu](#ubuntu)
|
||||
- [Fedora/RHEL](#fedorarhel)
|
||||
- [Arch Linux community](#arch-linux-community)
|
||||
- [NixOS](#nixos)
|
||||
- [macOS](#macos)
|
||||
- [Homebrew Core](#homebrew-core)
|
||||
- [Windows](#windows)
|
||||
- [Scoop](#scoop)
|
||||
- [Chocolatey](#chocolatey)
|
||||
- [MSYS2](#msys2)
|
||||
- [Building from source](#building-from-source)
|
||||
- [Configuring Helix's runtime files](#configuring-helixs-runtime-files)
|
||||
- [Validating the installation](#validating-the-installation)
|
||||
- [Configure the desktop shortcut](#configure-the-desktop-shortcut)
|
||||
<!--toc:end-->
|
||||
|
||||
To install Helix, follow the instructions specific to your operating system.
|
||||
Note that:
|
||||
|
||||
- To get the latest nightly version of Helix, you need to
|
||||
[build from source](#building-from-source).
|
||||
|
||||
- To take full advantage of Helix, install the language servers for your
|
||||
preferred programming languages. See the
|
||||
[wiki](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers)
|
||||
for instructions.
|
||||
|
||||
## Pre-built binaries
|
||||
|
||||
Download pre-built binaries from the
|
||||
[GitHub Releases page](https://github.com/helix-editor/helix/releases). Add the binary to your system's `$PATH` to use it from the command
|
||||
line.
|
||||
|
||||
## Linux, macOS, Windows and OpenBSD packaging status
|
||||
|
||||
Helix is available for Linux, macOS and Windows via the official repositories listed below.
|
||||
|
||||
[](https://repology.org/project/helix/versions)
|
||||
|
||||
## OSX
|
||||
|
||||
Helix is available in homebrew-core:
|
||||
|
||||
```
|
||||
brew install helix
|
||||
```
|
||||
|
||||
## Linux
|
||||
|
||||
### NixOS
|
||||
The following third party repositories are available:
|
||||
|
||||
A [flake](https://nixos.wiki/wiki/Flakes) containing the package is available in
|
||||
the project root. The flake can also be used to spin up a reproducible development
|
||||
shell for working on Helix with `nix develop`.
|
||||
### Ubuntu
|
||||
|
||||
Flake outputs are cached for each push to master using
|
||||
[Cachix](https://www.cachix.org/). The flake is configured to
|
||||
automatically make use of this cache assuming the user accepts
|
||||
the new settings on first use.
|
||||
|
||||
If you are using a version of Nix without flakes enabled you can
|
||||
[install Cachix cli](https://docs.cachix.org/installation); `cachix use helix` will
|
||||
configure Nix to use cached outputs when possible.
|
||||
|
||||
### Arch Linux
|
||||
|
||||
Releases are available in the `community` repository.
|
||||
|
||||
A [helix-git](https://aur.archlinux.org/packages/helix-git/) package is also available on the AUR, which builds the master branch.
|
||||
|
||||
### Fedora Linux
|
||||
|
||||
You can install the COPR package for Helix via
|
||||
Helix is available via [Maveonair's PPA](https://launchpad.net/~maveonair/+archive/ubuntu/helix-editor):
|
||||
|
||||
```sh
|
||||
sudo add-apt-repository ppa:maveonair/helix-editor
|
||||
sudo apt update
|
||||
sudo apt install helix
|
||||
```
|
||||
|
||||
### Fedora/RHEL
|
||||
|
||||
Helix is available via `copr`:
|
||||
|
||||
```sh
|
||||
sudo dnf copr enable varlad/helix
|
||||
sudo dnf install helix
|
||||
```
|
||||
|
||||
### Void Linux
|
||||
### Arch Linux community
|
||||
|
||||
Releases are available in the `community` repository:
|
||||
|
||||
```sh
|
||||
sudo pacman -S helix
|
||||
```
|
||||
sudo xbps-install helix
|
||||
Additionally, a [helix-git](https://aur.archlinux.org/packages/helix-git/) package is available
|
||||
in the AUR, which builds the master branch.
|
||||
|
||||
### NixOS
|
||||
|
||||
Helix is available as a [flake](https://nixos.wiki/wiki/Flakes) in the project
|
||||
root. Use `nix develop` to spin up a reproducible development shell. Outputs are
|
||||
cached for each push to master using [Cachix](https://www.cachix.org/). The
|
||||
flake is configured to automatically make use of this cache assuming the user
|
||||
accepts the new settings on first use.
|
||||
|
||||
If you are using a version of Nix without flakes enabled,
|
||||
[install Cachix CLI](https://docs.cachix.org/installation) and use
|
||||
`cachix use helix` to configure Nix to use cached outputs when possible.
|
||||
|
||||
## macOS
|
||||
|
||||
### Homebrew Core
|
||||
|
||||
```sh
|
||||
brew install helix
|
||||
```
|
||||
|
||||
## Windows
|
||||
|
||||
Helix can be installed using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/)
|
||||
Install on Windows using [Scoop](https://scoop.sh/), [Chocolatey](https://chocolatey.org/)
|
||||
or [MSYS2](https://msys2.org/).
|
||||
|
||||
**Scoop:**
|
||||
### Scoop
|
||||
|
||||
```
|
||||
```sh
|
||||
scoop install helix
|
||||
```
|
||||
|
||||
**Chocolatey:**
|
||||
### Chocolatey
|
||||
|
||||
```
|
||||
```sh
|
||||
choco install helix
|
||||
```
|
||||
|
||||
**MSYS2:**
|
||||
### MSYS2
|
||||
|
||||
Choose the [proper command](https://www.msys2.org/docs/package-naming/) for your system from below:
|
||||
For 64-bit Windows 8.1 or above:
|
||||
|
||||
- For 32 bit Windows 7 or above:
|
||||
|
||||
```
|
||||
pacman -S mingw-w64-i686-helix
|
||||
```
|
||||
|
||||
- For 64 bit Windows 7 or above:
|
||||
|
||||
```
|
||||
pacman -S mingw-w64-x86_64-helix
|
||||
```
|
||||
|
||||
- For 64 bit Windows 8.1 or above:
|
||||
|
||||
```
|
||||
```sh
|
||||
pacman -S mingw-w64-ucrt-x86_64-helix
|
||||
```
|
||||
|
||||
## Build from source
|
||||
## Building from source
|
||||
|
||||
```
|
||||
Clone the repository:
|
||||
|
||||
```sh
|
||||
git clone https://github.com/helix-editor/helix
|
||||
cd helix
|
||||
```
|
||||
|
||||
Compile from source:
|
||||
|
||||
```sh
|
||||
cargo install --path helix-term --locked
|
||||
```
|
||||
|
||||
This will install the `hx` binary to `$HOME/.cargo/bin` and build tree-sitter grammars in `./runtime/grammars`.
|
||||
This command will create the `hx` executable and construct the tree-sitter
|
||||
grammars either in the `runtime` folder, or in the folder specified in `HELIX_RUNTIME`
|
||||
(as described below). To build the tree-sitter grammars requires a c++ compiler to be installed, for example `gcc-c++`.
|
||||
|
||||
If you are using the musl-libc instead of glibc the following environment variable must be set during the build
|
||||
to ensure tree sitter grammars can be loaded correctly:
|
||||
> 💡 If you are using the musl-libc instead of glibc the following environment variable must be set during the build
|
||||
> to ensure tree-sitter grammars can be loaded correctly:
|
||||
>
|
||||
> ```sh
|
||||
> RUSTFLAGS="-C target-feature=-crt-static"
|
||||
> ```
|
||||
|
||||
```
|
||||
RUSTFLAGS="-C target-feature=-crt-static"
|
||||
> 💡 Tree-sitter grammars can be fetched and compiled if not pre-packaged. Fetch
|
||||
> grammars with `hx --grammar fetch` (requires `git`) and compile them with
|
||||
> `hx --grammar build` (requires a C++ compiler).
|
||||
|
||||
### Configuring Helix's runtime files
|
||||
|
||||
- **Linux and macOS**
|
||||
|
||||
Either set the `HELIX_RUNTIME` environment variable to point to the runtime files and add it to your `~/.bashrc` or equivalent:
|
||||
|
||||
```sh
|
||||
HELIX_RUNTIME=/home/user-name/src/helix/runtime
|
||||
```
|
||||
|
||||
Or, create a symlink in `~/.config/helix` that links to the source code directory:
|
||||
|
||||
Helix also needs its runtime files so make sure to copy/symlink the `runtime/` directory into the
|
||||
config directory (for example `~/.config/helix/runtime` on Linux/macOS). This location can be overridden
|
||||
via the `HELIX_RUNTIME` environment variable.
|
||||
|
||||
| OS | Command |
|
||||
| -------------------- | ------------------------------------------------ |
|
||||
| Windows (Cmd) | `xcopy /e /i runtime %AppData%\helix\runtime` |
|
||||
| Windows (PowerShell) | `xcopy /e /i runtime $Env:AppData\helix\runtime` |
|
||||
| Linux / macOS | `ln -s $PWD/runtime ~/.config/helix/runtime` |
|
||||
|
||||
Starting with Windows Vista you can also create symbolic links on Windows. Note that this requires
|
||||
elevated privileges - i.e. PowerShell or Cmd must be run as administrator.
|
||||
|
||||
**PowerShell:**
|
||||
|
||||
```powershell
|
||||
New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"
|
||||
```
|
||||
Note: "runtime" must be the absolute path to the runtime directory.
|
||||
|
||||
**Cmd:**
|
||||
|
||||
```cmd
|
||||
cd %appdata%\helix
|
||||
mklink /D runtime "<helix-repo>\runtime"
|
||||
```sh
|
||||
ln -s $PWD/runtime ~/.config/helix/runtime
|
||||
```
|
||||
|
||||
The runtime location can be overridden via the `HELIX_RUNTIME` environment variable.
|
||||
- **Windows**
|
||||
|
||||
> NOTE: if `HELIX_RUNTIME` is set prior to calling `cargo install --path helix-term --locked`,
|
||||
> tree-sitter grammars will be built in `$HELIX_RUNTIME/grammars`.
|
||||
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:
|
||||
|
||||
If you plan on keeping the repo locally, an alternative to copying/symlinking
|
||||
runtime files is to set `HELIX_RUNTIME=/path/to/helix/runtime`
|
||||
(`HELIX_RUNTIME=$PWD/runtime` if you're in the helix repo directory).
|
||||
|
||||
To use Helix in desktop environments that supports [XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html), including Gnome and KDE, copy the provided `.desktop` file to the correct folder:
|
||||
|
||||
```bash
|
||||
cp contrib/Helix.desktop ~/.local/share/applications
|
||||
```sh
|
||||
setx HELIX_RUNTIME "%userprofile%\source\repos\helix\runtime"
|
||||
```
|
||||
|
||||
To use another terminal than the default, you will need to modify the `.desktop` file. For example, to use `kitty`:
|
||||
> 💡 `%userprofile%` resolves to your user directory like
|
||||
> `C:\Users\Your-Name\` for example.
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
Or, create a symlink in `%appdata%\helix\` that links to the source code directory:
|
||||
|
||||
Please note: there is no icon for Helix yet, so the system default will be used.
|
||||
| Method | Command |
|
||||
| ---------- | -------------------------------------------------------------------------------------- |
|
||||
| PowerShell | `New-Item -ItemType Junction -Target "runtime" -Path "$Env:AppData\helix\runtime"` |
|
||||
| Cmd | `cd %appdata%\helix` <br/> `mklink /D runtime "%userprofile%\src\helix\runtime"` |
|
||||
|
||||
## Finishing up the installation
|
||||
> 💡 On Windows, creating a symbolic link may require running PowerShell or
|
||||
> Cmd as an administrator.
|
||||
|
||||
To make sure everything is set up as expected you should finally run the helix healthcheck via
|
||||
### Validating the installation
|
||||
|
||||
```
|
||||
To make sure everything is set up as expected you should run the Helix health
|
||||
check:
|
||||
|
||||
```sh
|
||||
hx --health
|
||||
```
|
||||
|
||||
For more information on the information displayed in the health check results refer to [Healthcheck](https://github.com/helix-editor/helix/wiki/Healthcheck).
|
||||
For more information on the health check results refer to
|
||||
[Health check](https://github.com/helix-editor/helix/wiki/Healthcheck).
|
||||
|
||||
### Building tree-sitter grammars
|
||||
### Configure the desktop shortcut
|
||||
|
||||
Tree-sitter grammars must be fetched and compiled if not pre-packaged.
|
||||
Fetch grammars with `hx --grammar fetch` (requires `git`) and compile them
|
||||
with `hx --grammar build` (requires a C++ compiler).
|
||||
If your desktop environment supports the
|
||||
[XDG desktop menu](https://specifications.freedesktop.org/menu-spec/menu-spec-latest.html)
|
||||
you can configure Helix to show up in the application menu by copying the
|
||||
provided `.desktop` and icon files to their correct folders:
|
||||
|
||||
### Installing language servers
|
||||
```sh
|
||||
cp contrib/Helix.desktop ~/.local/share/applications
|
||||
cp contrib/helix.png ~/.icons # or ~/.local/share/icons
|
||||
```
|
||||
|
||||
Language servers can optionally be installed if you want their features (auto-complete, diagnostics etc.).
|
||||
Follow the [instructions on the wiki page](https://github.com/helix-editor/helix/wiki/How-to-install-the-default-language-servers) to add your language servers of choice.
|
||||
To use another terminal than the system default, you can modify the `.desktop`
|
||||
file. For example, to use `kitty`:
|
||||
|
||||
```sh
|
||||
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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -14,14 +14,14 @@
|
|||
- [Space mode](#space-mode)
|
||||
- [Popup](#popup)
|
||||
- [Unimpaired](#unimpaired)
|
||||
- [Insert Mode](#insert-mode)
|
||||
- [Select / extend mode](#select--extend-mode)
|
||||
- [Insert mode](#insert-mode)
|
||||
- [Select / extend mode](#select-extend-mode)
|
||||
- [Picker](#picker)
|
||||
- [Prompt](#prompt)
|
||||
|
||||
> 💡 Mappings marked (**LSP**) require an active language server for the file.
|
||||
|
||||
> 💡 Mappings marked (**TS**) require a tree-sitter grammar for the filetype.
|
||||
> 💡 Mappings marked (**TS**) require a tree-sitter grammar for the file type.
|
||||
|
||||
## Normal mode
|
||||
|
||||
|
|
@ -109,7 +109,7 @@
|
|||
| Key | Description | Command |
|
||||
| ----- | ----------- | ------- |
|
||||
| `s` | Select all regex matches inside selections | `select_regex` |
|
||||
| `S` | Split selection into subselections on regex matches | `split_selection` |
|
||||
| `S` | Split selection into sub selections on regex matches | `split_selection` |
|
||||
| `Alt-s` | Split selection on newlines | `split_selection_on_newline` |
|
||||
| `Alt-_ ` | Merge consecutive selections | `merge_consecutive_selections` |
|
||||
| `&` | Align selection in columns | `align_selections` |
|
||||
|
|
@ -141,7 +141,7 @@
|
|||
|
||||
### Search
|
||||
|
||||
Search commands all operate on the `/` register by default. Use `"<char>` to operate on a different one.
|
||||
Search commands all operate on the `/` register by default. To use a different register, use `"<char>`.
|
||||
|
||||
| Key | Description | Command |
|
||||
| ----- | ----------- | ------- |
|
||||
|
|
@ -175,9 +175,8 @@ Accessed by typing `z` in [normal mode](#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
|
||||
normal mode) is persistent; use the Escape key to return to normal mode after
|
||||
usage (useful when you're simply looking over text and not actively editing
|
||||
it).
|
||||
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 |
|
||||
|
|
@ -225,7 +224,7 @@ Jumps to various locations.
|
|||
Accessed by typing `m` in [normal mode](#normal-mode).
|
||||
|
||||
See the relevant section in [Usage](./usage.md) for an explanation about
|
||||
[surround](./usage.md#surround) and [textobject](./usage.md#textobjects) usage.
|
||||
[surround](./usage.md#surround) and [textobject](./usage.md#navigating-using-tree-sitter-textobjects) usage.
|
||||
|
||||
| Key | Description | Command |
|
||||
| ----- | ----------- | ------- |
|
||||
|
|
@ -242,7 +241,7 @@ TODO: Mappings for selecting syntax nodes (a superset of `[`).
|
|||
|
||||
Accessed by typing `Ctrl-w` in [normal mode](#normal-mode).
|
||||
|
||||
This layer is similar to Vim keybindings as Kakoune does not support window.
|
||||
This layer is similar to Vim keybindings as Kakoune does not support windows.
|
||||
|
||||
| Key | Description | Command |
|
||||
| ----- | ------------- | ------- |
|
||||
|
|
@ -293,7 +292,7 @@ This layer is a kludge of mappings, mostly pickers.
|
|||
| `/` | Global search in workspace folder | `global_search` |
|
||||
| `?` | Open command palette | `command_palette` |
|
||||
|
||||
> TIP: Global search displays results in a fuzzy picker, use `Space + '` to bring it back up after opening a file.
|
||||
> 💡 Global search displays results in a fuzzy picker, use `Space + '` to bring it back up after opening a file.
|
||||
|
||||
##### Popup
|
||||
|
||||
|
|
@ -306,7 +305,7 @@ Displays documentation for item under cursor.
|
|||
|
||||
#### Unimpaired
|
||||
|
||||
Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired).
|
||||
These mappings are in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired).
|
||||
|
||||
| Key | Description | Command |
|
||||
| ----- | ----------- | ------- |
|
||||
|
|
@ -335,12 +334,13 @@ Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaire
|
|||
|
||||
## Insert mode
|
||||
|
||||
Insert mode bindings are somewhat minimal by default. Helix is designed to
|
||||
Insert mode bindings are minimal by default. Helix is designed to
|
||||
be a modal editor, and this is reflected in the user experience and internal
|
||||
mechanics. For example, changes to the text are only saved for undos when
|
||||
escaping from insert mode to normal mode. For this reason, new users are
|
||||
strongly encouraged to learn the modal editing paradigm to get the smoothest
|
||||
experience.
|
||||
mechanics. Changes to the text are only saved for undos when
|
||||
escaping from insert mode to normal mode.
|
||||
|
||||
> 💡 New users are strongly encouraged to learn the modal editing paradigm
|
||||
> to get the smoothest experience.
|
||||
|
||||
| Key | Description | Command |
|
||||
| ----- | ----------- | ------- |
|
||||
|
|
@ -370,8 +370,8 @@ with modal editors.
|
|||
| `Home` | Move to line start | `goto_line_start` |
|
||||
| `End` | Move to line end | `goto_line_end_newline` |
|
||||
|
||||
If you want to disable them in insert mode as you become more comfortable with modal editing, you can use
|
||||
the following in your `config.toml`:
|
||||
As 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.
|
||||
|
||||
```toml
|
||||
[keys.insert]
|
||||
|
|
@ -387,7 +387,7 @@ end = "no_op"
|
|||
|
||||
## Select / extend mode
|
||||
|
||||
This mode echoes Normal mode, but changes any movements to extend
|
||||
Select mode echoes Normal mode, but changes any movements to extend
|
||||
selections rather than replace them. Goto motions are also changed to
|
||||
extend, so that `vgl` for example extends the selection to the end of
|
||||
the line.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,10 @@
|
|||
# Language Support
|
||||
|
||||
The following languages and Language Servers are supported. In order to use
|
||||
The following languages and Language Servers are supported. To use
|
||||
Language Server features, you must first [install][lsp-install-wiki] the
|
||||
appropriate Language Server.
|
||||
|
||||
Check the language support in your installed helix version with `hx --health`.
|
||||
You can check the language support in your installed helix version with `hx --health`.
|
||||
|
||||
Also see the [Language Configuration][lang-config] docs and the [Adding
|
||||
Languages][adding-languages] guide for more language configuration information.
|
||||
|
|
|
|||
|
|
@ -5,13 +5,15 @@ in `languages.toml` files.
|
|||
|
||||
## `languages.toml` files
|
||||
|
||||
There are three possible `languages.toml` files. The first is compiled into
|
||||
Helix and lives in the [Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml).
|
||||
This provides the default configurations for languages and language servers.
|
||||
There are three possible locations for a `languages.toml` file:
|
||||
|
||||
You may define a `languages.toml` in your [configuration directory](./configuration.md)
|
||||
which overrides values from the built-in language configuration. For example
|
||||
to disable auto-LSP-formatting in Rust:
|
||||
1. In the Helix source code, this lives in the
|
||||
[Helix repository](https://github.com/helix-editor/helix/blob/master/languages.toml).
|
||||
It provides the default configurations for languages and language servers.
|
||||
|
||||
2. In your [configuration directory](./configuration.md). This overrides values
|
||||
from the built-in language configuration. For example to disable
|
||||
auto-LSP-formatting in Rust:
|
||||
|
||||
```toml
|
||||
# in <config_dir>/helix/languages.toml
|
||||
|
|
@ -21,10 +23,10 @@ name = "rust"
|
|||
auto-format = false
|
||||
```
|
||||
|
||||
Language configuration may also be overridden local to a project by creating
|
||||
a `languages.toml` file under a `.helix` directory. Its settings will be merged
|
||||
with the language configuration in the configuration directory and the built-in
|
||||
configuration.
|
||||
3. In a `.helix` folder in your project. Language configuration may also be
|
||||
overridden local to a project by creating a `languages.toml` file in a
|
||||
`.helix` folder. Its settings will be merged with the language configuration
|
||||
in the configuration directory and the built-in configuration.
|
||||
|
||||
## Language configuration
|
||||
|
||||
|
|
@ -65,7 +67,7 @@ These configuration keys are available:
|
|||
|
||||
### File-type detection and the `file-types` key
|
||||
|
||||
Helix determines which language configuration to use with the `file-types` key
|
||||
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:
|
||||
|
||||
|
|
|
|||
|
|
@ -1,18 +1,18 @@
|
|||
# Key Remapping
|
||||
# Key remapping
|
||||
|
||||
One-way key remapping is temporarily supported via a simple TOML configuration
|
||||
Helix currently supports one-way key remapping through a simple TOML configuration
|
||||
file. (More powerful solutions such as rebinding via commands will be
|
||||
available in the future).
|
||||
|
||||
To remap keys, write a `config.toml` file in your `helix` configuration
|
||||
directory (default `~/.config/helix` in Linux systems) with a structure like
|
||||
To remap keys, create a `config.toml` file in your `helix` configuration
|
||||
directory (default `~/.config/helix` on Linux systems) with a structure like
|
||||
this:
|
||||
|
||||
```toml
|
||||
# At most one section each of 'keys.normal', 'keys.insert' and 'keys.select'
|
||||
[keys.normal]
|
||||
C-s = ":w" # Maps the Ctrl-s to the typable command :w which is an alias for :write (save file)
|
||||
C-o = ":open ~/.config/helix/config.toml" # Maps the Ctrl-o to opening of the helix config file
|
||||
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
|
||||
|
|
@ -20,10 +20,9 @@ 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
|
||||
"A-x" = "normal_mode" # Maps Alt-X to enter normal mode
|
||||
j = { k = "normal_mode" } # Maps `jk` to exit insert mode
|
||||
```
|
||||
> NOTE: Typable commands can also be remapped, remember to keep the `:` prefix to indicate it's a typable command.
|
||||
|
||||
## Minor modes
|
||||
|
||||
|
|
@ -76,5 +75,5 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes
|
|||
|
||||
Keys can be disabled by binding them to the `no_op` command.
|
||||
|
||||
Commands can be found at [Keymap](https://docs.helix-editor.com/keymap.html) Commands.
|
||||
> Commands can also be found in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`.
|
||||
A list of commands is available in the [Keymap](https://docs.helix-editor.com/keymap.html) documentation
|
||||
and in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) at the invocation of `static_commands!` macro and the `TypableCommandList`.
|
||||
|
|
|
|||
|
|
@ -1,14 +1,15 @@
|
|||
# Themes
|
||||
|
||||
To use a theme add `theme = "<name>"` to your [`config.toml`](./configuration.md) at the very top of the file before the first section or select it during runtime using `:theme <name>`.
|
||||
To use a theme add `theme = "<name>"` to the top of your [`config.toml`](./configuration.md) file, or select it during runtime using `:theme <name>`.
|
||||
|
||||
## Creating a theme
|
||||
|
||||
Create a file with the name of your theme as file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes`). The directory might have to be created beforehand.
|
||||
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 the builtin themes and cannot be overridden by user defined themes.
|
||||
> 💡 The names "default" and "base16_default" are reserved for built-in themes
|
||||
> and cannot be overridden by user-defined themes.
|
||||
|
||||
The default theme.toml can be found [here](https://github.com/helix-editor/helix/blob/master/theme.toml), and user submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes).
|
||||
### Overview
|
||||
|
||||
Each line in the theme file is specified as below:
|
||||
|
||||
|
|
@ -16,7 +17,7 @@ Each line in the theme file is specified as below:
|
|||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -24,15 +25,30 @@ To specify only the foreground color:
|
|||
key = "#ffffff"
|
||||
```
|
||||
|
||||
if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).
|
||||
If the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).
|
||||
|
||||
```toml
|
||||
"key.key" = "#ffffff"
|
||||
```
|
||||
|
||||
For inspiration, you can find the default `theme.toml`
|
||||
[here](https://github.com/helix-editor/helix/blob/master/theme.toml) and
|
||||
user-submitted themes
|
||||
[here](https://github.com/helix-editor/helix/blob/master/runtime/themes).
|
||||
|
||||
### Using the linter
|
||||
|
||||
Use the supplied linting tool to check for errors and missing scopes:
|
||||
|
||||
```sh
|
||||
cargo xtask themelint onedark # replace onedark with <name>
|
||||
```
|
||||
|
||||
## The details of theme creation
|
||||
|
||||
### Color palettes
|
||||
|
||||
It's recommended define a palette of named colors, and refer to them from the
|
||||
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:
|
||||
|
||||
|
|
@ -45,8 +61,8 @@ white = "#ffffff"
|
|||
black = "#000000"
|
||||
```
|
||||
|
||||
Remember that the `[palette]` table includes all keys after its header,
|
||||
so you should define the palette after normal theme options.
|
||||
Keep in mind that the `[palette]` table includes all keys after its header,
|
||||
so it should be defined after the normal theme options.
|
||||
|
||||
The default palette uses the terminal's default 16 colors, and the colors names
|
||||
are listed below. The `[palette]` section in the config file takes precedence
|
||||
|
|
@ -73,9 +89,8 @@ over it and is merged into the default palette.
|
|||
|
||||
### Modifiers
|
||||
|
||||
The following values may be used as modifiers.
|
||||
|
||||
Less common modifiers might not be supported by your terminal emulator.
|
||||
The following values may be used as modifier, provided they are supported by
|
||||
your terminal emulator.
|
||||
|
||||
| Modifier |
|
||||
| --- |
|
||||
|
|
@ -89,14 +104,13 @@ Less common modifiers might not be supported by your terminal emulator.
|
|||
| `hidden` |
|
||||
| `crossed_out` |
|
||||
|
||||
> Note: The `underlined` modifier is deprecated and only available for backwards compatibility.
|
||||
> 💡 The `underlined` modifier is deprecated and only available for backwards compatibility.
|
||||
> Its behavior is equivalent to setting `underline.style="line"`.
|
||||
|
||||
### Underline Style
|
||||
### Underline style
|
||||
|
||||
One of the following values may be used as a value for `underline.style`.
|
||||
|
||||
Some styles might not be supported by your terminal emulator.
|
||||
One of the following values may be used as a value for `underline.style`, providing it is
|
||||
supported by your terminal emulator.
|
||||
|
||||
| Modifier |
|
||||
| --- |
|
||||
|
|
@ -109,7 +123,7 @@ Some styles might not be supported by your terminal emulator.
|
|||
|
||||
### Inheritance
|
||||
|
||||
Extend upon other themes by setting the `inherits` property to an existing theme.
|
||||
Extend other themes by setting the `inherits` property to an existing theme.
|
||||
|
||||
```toml
|
||||
inherits = "boo_berry"
|
||||
|
|
@ -124,19 +138,19 @@ berry = "#2A2A4D"
|
|||
|
||||
### Scopes
|
||||
|
||||
The following is a list of scopes available to use for styling.
|
||||
The following is a list of scopes available to use for styling:
|
||||
|
||||
#### Syntax highlighting
|
||||
|
||||
These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme).
|
||||
|
||||
For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight `function.builtin.static` would match the key `function.builtin` rather than `function`.
|
||||
When determining styling for a highlight, the longest matching theme key will be used. For example, if the highlight is `function.builtin.static`, the key `function.builtin` will be used instead of `function`.
|
||||
|
||||
We use a similar set of scopes as
|
||||
[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also
|
||||
[Sublime Text](https://www.sublimetext.com/docs/scope_naming.html). See also
|
||||
[TextMate](https://macromates.com/manual/en/language_grammars) scopes.
|
||||
|
||||
- `attribute` - Class attributes, html tag attributes
|
||||
- `attribute` - Class attributes, HTML tag attributes
|
||||
|
||||
- `type` - Types
|
||||
- `builtin` - Primitive types provided by the language (`int`, `usize`)
|
||||
|
|
@ -144,7 +158,7 @@ We use a similar set of scopes as
|
|||
- `variant`
|
||||
- `constructor`
|
||||
|
||||
- `constant` (TODO: constant.other.placeholder for %v)
|
||||
- `constant` (TODO: constant.other.placeholder for `%v`)
|
||||
- `builtin` Special constants provided by the language (`true`, `false`, `nil` etc)
|
||||
- `boolean`
|
||||
- `character`
|
||||
|
|
@ -162,11 +176,11 @@ We use a similar set of scopes as
|
|||
|
||||
- `comment` - Code comments
|
||||
- `line` - Single line comments (`//`)
|
||||
- `block` - Block comments (e.g. (`/* */`)
|
||||
- `block` - Block comments (e.g. (`/* */`)
|
||||
- `documentation` - Documentation comments (e.g. `///` in Rust)
|
||||
|
||||
- `variable` - Variables
|
||||
- `builtin` - Reserved language variables (`self`, `this`, `super`, etc)
|
||||
- `builtin` - Reserved language variables (`self`, `this`, `super`, etc.)
|
||||
- `parameter` - Function parameters
|
||||
- `other`
|
||||
- `member` - Fields of composite data types (e.g. structs, unions)
|
||||
|
|
@ -216,9 +230,9 @@ We use a similar set of scopes as
|
|||
- `bold`
|
||||
- `italic`
|
||||
- `link`
|
||||
- `url` - urls pointed to by links
|
||||
- `label` - non-url link references
|
||||
- `text` - url and image descriptions in links
|
||||
- `url` - URLs pointed to by links
|
||||
- `label` - non-URL link references
|
||||
- `text` - URL and image descriptions in links
|
||||
- `quote`
|
||||
- `raw`
|
||||
- `inline`
|
||||
|
|
@ -232,19 +246,19 @@ We use a similar set of scopes as
|
|||
|
||||
#### Interface
|
||||
|
||||
These scopes are used for theming the editor interface.
|
||||
These scopes are used for theming the editor interface:
|
||||
|
||||
- `markup`
|
||||
- `normal`
|
||||
- `completion` - for completion doc popup ui
|
||||
- `hover` - for hover popup ui
|
||||
- `completion` - for completion doc popup UI
|
||||
- `hover` - for hover popup UI
|
||||
- `heading`
|
||||
- `completion` - for completion doc popup ui
|
||||
- `hover` - for hover popup ui
|
||||
- `completion` - for completion doc popup UI
|
||||
- `hover` - for hover popup UI
|
||||
- `raw`
|
||||
- `inline`
|
||||
- `completion` - for completion doc popup ui
|
||||
- `hover` - for hover popup ui
|
||||
- `completion` - for completion doc popup UI
|
||||
- `hover` - for hover popup UI
|
||||
|
||||
|
||||
| Key | Notes |
|
||||
|
|
@ -270,9 +284,9 @@ These scopes are used for theming the editor interface.
|
|||
| `ui.statusline.insert` | Statusline mode during insert mode ([only if `editor.color-modes` is enabled][editor-section]) |
|
||||
| `ui.statusline.select` | Statusline mode during select mode ([only if `editor.color-modes` is enabled][editor-section]) |
|
||||
| `ui.statusline.separator` | Separator character in statusline |
|
||||
| `ui.popup` | Documentation popups (e.g Space + k) |
|
||||
| `ui.popup` | Documentation popups (e.g. Space + k) |
|
||||
| `ui.popup.info` | Prompt for multiple key options |
|
||||
| `ui.window` | Border lines separating splits |
|
||||
| `ui.window` | Borderlines separating splits |
|
||||
| `ui.help` | Description box for commands |
|
||||
| `ui.text` | Command prompts, popup text, etc. |
|
||||
| `ui.text.focus` | |
|
||||
|
|
@ -301,10 +315,4 @@ These scopes are used for theming the editor interface.
|
|||
| `diagnostic.warning` | Diagnostics warning (editing area) |
|
||||
| `diagnostic.error` | Diagnostics error (editing area) |
|
||||
|
||||
You can check compliance to spec with
|
||||
|
||||
```shell
|
||||
cargo xtask themelint onedark # replace onedark with <name>
|
||||
```
|
||||
|
||||
[editor-section]: ./configuration.md#editor-section
|
||||
|
|
|
|||
|
|
@ -1,22 +1,43 @@
|
|||
# Usage
|
||||
# Using Helix
|
||||
|
||||
(Currently not fully documented, see the [keymappings](./keymap.md) list for more.)
|
||||
<!--toc:start-->
|
||||
- [Registers](#registers)
|
||||
- [User-defined registers](#user-defined-registers)
|
||||
- [Special registers](#special-registers)
|
||||
- [Surround](#surround)
|
||||
- [Selecting and manipulating text with textobjects](#selecting-and-manipulating-text-with-textobjects)
|
||||
- [Navigating using tree-sitter textobjects](#navigating-using-tree-sitter-textobjects)
|
||||
- [Moving the selection with syntax-aware motions](#moving-the-selection-with-syntax-aware-motions)
|
||||
<!--toc:end-->
|
||||
|
||||
See [tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) (accessible via `hx --tutor` or `:tutor`) for a vimtutor-like introduction.
|
||||
For a full interactive introduction to Helix, refer to the
|
||||
[tutor](https://github.com/helix-editor/helix/blob/master/runtime/tutor) which
|
||||
can be accessed via the command `hx --tutor` or `:tutor`.
|
||||
|
||||
> 💡 Currently, not all functionality is fully documented, please refer to the
|
||||
> [key mappings](./keymap.md) list.
|
||||
|
||||
## Registers
|
||||
|
||||
Vim-like registers can be used to yank and store text to be pasted later. Usage is similar, with `"` being used to select a register:
|
||||
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
|
||||
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.
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
### Special Registers
|
||||
### Special registers
|
||||
|
||||
| Register character | Contains |
|
||||
| --- | --- |
|
||||
|
|
@ -25,41 +46,90 @@ If there is a selected register before invoking a change or delete command, the
|
|||
| `"` | Last yanked text |
|
||||
| `_` | Black hole |
|
||||
|
||||
> There is no special register for copying to system clipboard, instead special commands and keybindings are provided. See the [keymap](keymap.md#space-mode) for the specifics.
|
||||
> The black hole register works as a no-op register, meaning no data will be written to / read from it.
|
||||
The system clipboard is not directly supported by a special register. Instead, special commands and keybindings are provided. Refer to the
|
||||
[key map](keymap.md#space-mode) for more details.
|
||||
|
||||
The black hole register is a no-op register, meaning that no data will be read or written to it.
|
||||
|
||||
## Surround
|
||||
|
||||
Functionality similar to [vim-surround](https://github.com/tpope/vim-surround) is built into
|
||||
helix. The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):
|
||||
Helix includes built-in functionality similar to [vim-surround](https://github.com/tpope/vim-surround).
|
||||
The keymappings have been inspired from [vim-sandwich](https://github.com/machakann/vim-sandwich):
|
||||
|
||||
|
||||
|
||||
|
||||
- `ms` - Add surround characters
|
||||
- `mr` - Replace surround characters
|
||||
- `md` - Delete surround characters
|
||||
| Key Sequence | Action |
|
||||
| --------------------------------- | --------------------------------------- |
|
||||
| `ms<char>` (after selecting text) | Add surround characters to selection |
|
||||
| `mr<char_to_replace><new_char>` | Replace the closest surround characters |
|
||||
| `md<char_to_delete>` | Delete the closest surround characters |
|
||||
|
||||
`ms` acts on a selection, so select the text first and use `ms<char>`. `mr` and `md` work
|
||||
on the closest pairs found and selections are not required; use counts to act in outer pairs.
|
||||
You can use counts to act on outer pairs.
|
||||
|
||||
It can also act on multiple selections (yay!). For example, to change every occurrence of `(use)` to `[use]`:
|
||||
Surround can also act on multiple selections. For example, to change every occurrence of `(use)` to `[use]`:
|
||||
|
||||
- `%` to select the whole file
|
||||
- `s` to split the selections on a search term
|
||||
- Input `use` and hit Enter
|
||||
- `mr([` to replace the parens with square brackets
|
||||
1. `%` to select the whole file
|
||||
2. `s` to split the selections on a search term
|
||||
3. Input `use` and hit Enter
|
||||
4. `mr([` to replace the parentheses with square brackets
|
||||
|
||||
Multiple characters are currently not supported, but planned.
|
||||
Multiple characters are currently not supported, but planned for future release.
|
||||
|
||||
## Syntax-tree Motions
|
||||
## Selecting and manipulating text with textobjects
|
||||
|
||||
`Alt-p`, `Alt-o`, `Alt-i`, and `Alt-n` (or `Alt` and arrow keys) move the primary
|
||||
selection according to the selection's place in the syntax tree. Let's walk
|
||||
through an example to get familiar with them. Many languages have a syntax like
|
||||
so for function calls:
|
||||
In Helix, textobjects are a way to select, manipulate and operate on a piece of
|
||||
text in a structured way. They allow you to refer to blocks of text based on
|
||||
their structure or purpose, such as a word, sentence, paragraph, or even a
|
||||
function or block of code.
|
||||
|
||||
```
|
||||
func(arg1, arg2, arg3)
|
||||
|
||||
|
||||
|
||||
- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)
|
||||
- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)
|
||||
|
||||
| Key after `mi` or `ma` | Textobject selected |
|
||||
| --- | --- |
|
||||
| `w` | Word |
|
||||
| `W` | WORD |
|
||||
| `p` | Paragraph |
|
||||
| `(`, `[`, `'`, etc. | Specified surround pairs |
|
||||
| `m` | The closest surround pair |
|
||||
| `f` | Function |
|
||||
| `c` | Class |
|
||||
| `a` | Argument/parameter |
|
||||
| `o` | Comment |
|
||||
| `t` | Test |
|
||||
| `g` | Change |
|
||||
|
||||
> 💡 `f`, `c`, etc. need a tree-sitter grammar active for the current
|
||||
document and a special tree-sitter query file to work properly. [Only
|
||||
some grammars][lang-support] currently have the query file implemented.
|
||||
Contributions are welcome!
|
||||
|
||||
## Navigating using tree-sitter textobjects
|
||||
|
||||
Navigating between functions, classes, parameters, and other elements is
|
||||
possible using tree-sitter and textobject queries. For
|
||||
example to move to the next function use `]f`, to move to previous
|
||||
class use `[c`, and so on.
|
||||
|
||||
![Tree-sitter-nav-demo][tree-sitter-nav-demo]
|
||||
|
||||
For the full reference see the [unimpaired][unimpaired-keybinds] section of the key bind
|
||||
documentation.
|
||||
|
||||
> 💡 This feature relies on tree-sitter textobjects
|
||||
> 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
|
||||
selection according to its location in the syntax tree. For example, many languages have the
|
||||
following syntax for function calls:
|
||||
|
||||
```js
|
||||
func(arg1, arg2, arg3);
|
||||
```
|
||||
|
||||
A function call might be parsed by tree-sitter into a tree like the following.
|
||||
|
|
@ -93,77 +163,29 @@ a more intuitive tree format:
|
|||
└──────────┘ └──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
Say we have a selection that wraps `arg1`. The selection is on the `arg1` leaf
|
||||
in the tree above.
|
||||
If you have a selection that wraps `arg1` (see the tree above), and you use
|
||||
`Alt-n`, it will select the next sibling in the syntax tree: `arg2`.
|
||||
|
||||
```
|
||||
```js
|
||||
// before
|
||||
func([arg1], arg2, arg3)
|
||||
// after
|
||||
func(arg1, [arg2], arg3);
|
||||
```
|
||||
|
||||
Using `Alt-n` would select the next sibling in the syntax tree: `arg2`.
|
||||
Similarly, `Alt-o` will expand the selection to the parent node, in this case, the
|
||||
arguments node.
|
||||
|
||||
```
|
||||
func(arg1, [arg2], arg3)
|
||||
```
|
||||
|
||||
While `Alt-o` would expand the selection to the parent node. In the tree above we
|
||||
can see that we would select the `arguments` node.
|
||||
|
||||
```
|
||||
func[(arg1, arg2, arg3)]
|
||||
```js
|
||||
func[(arg1, arg2, arg3)];
|
||||
```
|
||||
|
||||
There is also some nuanced behavior that prevents you from getting stuck on a
|
||||
node with no sibling. If we have a selection on `arg1`, `Alt-p` would bring us
|
||||
to the previous child node. Since `arg1` doesn't have a sibling to its left,
|
||||
though, we climb the syntax tree and then take the previous selection. So
|
||||
`Alt-p` will move the selection over to the "func" `identifier`.
|
||||
|
||||
```
|
||||
[func](arg1, arg2, arg3)
|
||||
```
|
||||
|
||||
## Textobjects
|
||||
|
||||
|
||||
|
||||
|
||||
- `ma` - Select around the object (`va` in Vim, `<alt-a>` in Kakoune)
|
||||
- `mi` - Select inside the object (`vi` in Vim, `<alt-i>` in Kakoune)
|
||||
|
||||
| Key after `mi` or `ma` | Textobject selected |
|
||||
| --- | --- |
|
||||
| `w` | Word |
|
||||
| `W` | WORD |
|
||||
| `p` | Paragraph |
|
||||
| `(`, `[`, `'`, etc | Specified surround pairs |
|
||||
| `m` | Closest surround pair |
|
||||
| `f` | Function |
|
||||
| `c` | Class |
|
||||
| `a` | Argument/parameter |
|
||||
| `o` | Comment |
|
||||
| `t` | Test |
|
||||
| `g` | Change |
|
||||
|
||||
> NOTE: `f`, `c`, etc need a tree-sitter grammar active for the current
|
||||
document and a special tree-sitter query file to work properly. [Only
|
||||
some grammars][lang-support] currently have the query file implemented.
|
||||
Contributions are welcome!
|
||||
|
||||
## Tree-sitter Textobject Based Navigation
|
||||
|
||||
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 `]f`, to move to previous
|
||||
class use `[c`, and so on.
|
||||
|
||||
![tree-sitter-nav-demo][tree-sitter-nav-demo]
|
||||
|
||||
See the [unimpaired][unimpaired-keybinds] section of the keybind
|
||||
documentation for the full reference.
|
||||
|
||||
> NOTE: This feature is dependent on tree-sitter based textobjects
|
||||
and therefore requires the corresponding query file to work properly.
|
||||
node with no sibling. When using `Alt-p` with a selection on `arg1`, the previous
|
||||
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`.
|
||||
|
||||
[lang-support]: ./lang-support.md
|
||||
[unimpaired-keybinds]: ./keymap.md#unimpaired
|
||||
|
|
|
|||
Loading…
Reference in a new issue