Skip to content

Commit

Permalink
Update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@aaronik
aaronik committed Jan 14, 2025
1 parent 4992fa9 commit 1e7e23f
Showing 1 changed file with 44 additions and 33 deletions.
77 changes: 44 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,54 +1,65 @@
<a href="https://neovim.io/" style="vertical-align: middle;"><img src="https://img.shields.io/badge/NeoVim-%2357A143.svg?&amp;style=for-the-badge&amp;logo=neovim&amp;logoColor=white" alt="Neovim" style="height: 20px;"></a>
<span style="height: 20px;">
<img alt="Static Badge" src="https://img.shields.io/badge/100%25_lua-purple" style="height: 20px;">
</span>
![build status](https://github.com/aaronik/treewalker.nvim/actions/workflows/test.yml/badge.svg)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues/aaronik/treewalker.nvim)
![GitHub Issues or Pull Requests](https://img.shields.io/github/issues-pr/aaronik/treewalker.nvim)

# Treewalker.nvim
<div align="center">
<h1>Treewalker.nvim</h1>
<h4 align="center">
<a href="#Installation">Installation</a>
·
<a href="#Mapping">Mapping</a>
</h4>
<a href="https://neovim.io/">
<img alt="Neovim" style="height: 20px;" src="https://img.shields.io/badge/NeoVim-%2357A143.svg?&amp;style=for-the-badge&amp;logo=neovim&amp;logoColor=white">
</a>
<img alt="Static Badge" src="https://img.shields.io/badge/100%25_lua-purple" height="20px">
<img src="https://github.com/aaronik/treewalker.nvim/actions/workflows/test.yml/badge.svg" alt="build status">
<img src="https://img.shields.io/github/issues/aaronik/treewalker.nvim" alt="GitHub Issues">
<img src="https://img.shields.io/github/issues-pr/aaronik/treewalker.nvim" alt="GitHub Pull Requests">
</div>

<br>

![A fast paced demo of Treewalker.nvim](https://github.com/user-attachments/assets/4d23af49-bd94-412a-bc8c-d546df6775df)

Treewalker is a plugin that lets you **move around your code in a syntax tree aware manner**.
It uses neovim's native [Treesitter](https://github.com/tree-sitter/tree-sitter) under the hood for syntax tree awareness.
It has no dependencies, and is meant to "just work". It is "batteries included", with minimal configuration.
### Move around your code in a syntax tree aware manner.

Treewalker uses neovim's native [Treesitter](https://github.com/tree-sitter/tree-sitter) under the hood for syntax tree awareness.
It has no dependencies, and is meant to "just work". It's "batteries included", with minimal configuration.

---

### Movement
## Movement

The movement commands move you through the syntax tree in an intuitive way:

* **Up/Down** - Moves you up or down to the next neighbor node, skipping comments, annotations, and other unintuitive nodes
* **Right** - Moves to the next node that's indented further than the current node
* **Left** - Moves to the next ancestor node that's on a different line from the current node
* **`:Treewalker Up`** - Moves up to the previous neighbor node, skipping comments, annotations, and other unintuitive nodes
* **`:Treewalker Down`** - Moves down to the next neighbor node, skipping comments, annotations, and other unintuitive nodes
* **`:Treewalker Left`** - Moves to the first ancestor node that's on a different line from the current node
* **`:Treewalker Right`** - Moves to the next node down that's indented further than the current node

---

### Swapping
## Swapping

The swap commands swap nodes, but up/down bring along any comments, annotations, or decorators associated with that node:
The swap commands swap nodes, with up/down bringing along any comments, annotations, and decorators:

* **SwapUp/SwapDown** - Swaps nodes up or down in your document (so neighbor nodes), _bringing comments, annotations, and decorators._
These swaps will only bring stuff up and down relative to the document itself, so it'll only change nodes
_across different line numbers_. These are meant for swapping declarations and definitions.
* **SwapLeft/SwapRight** - These also swap neighbor nodes, but are literal about the definition of a node, whereas the up/down swaps
and movement take a lot of liberty to be "smart". Swap{Left/Right} are meant for swapping function arguments,
enum members, list elements, etc.
* **`:Treewalker SwapUp`** / **`:Treewalker SwapDown`** - Swaps nodes up or down in your document (so neighbor nodes), _bringing comments, annotations, and decorators._
These swaps will only bring stuff up and down relative to the document itself, so it'll only change nodes
_across different line numbers_. These are meant for swapping declarations and definitions.
* **`:Treewalker SwapLeft`** / **`:Treewalker SwapRight`** - These also swap neighbor nodes, but are literal about the definition of a node, whereas the up/down swaps
and movement take a lot of liberty to be "smart". `Swap{Left/Right}` are meant for swapping function arguments,
enum members, list elements, etc.

_There are other plugins that do mostly this Left/Right swapping behavior:_
_There are other plugins that do mostly this Left/Right swapping behavior:_

[nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects) - This can move around [a subset
of nodes](https://github.com/nvim-treesitter/nvim-treesitter-textobjects?tab=readme-ov-file#built-in-textobjects), but misses some
types (ex. rust enums). `Treewalker` is not aware of node type names, only the structure of the AST, so left/right swaps will work
everywhere you want it to.
[nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects) - This can move around [a subset
of nodes](https://github.com/nvim-treesitter/nvim-treesitter-textobjects?tab=readme-ov-file#built-in-textobjects), but misses some
types (ex. rust enums). `Treewalker` is not aware of node type names, only the structure of the AST, so left/right swaps will work
mostly where you want it to.

[nvim-treesitter.ts_utils](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/lua/nvim-treesitter/ts_utils.lua) - This doesn't
suffer from node name awareness, and works mostly the same as `Treewalker`. Some of `Treewalker`'s left/right swapping code is even
inspired by `ts_utils`. However `Treewalker` offers one fundamental difference - when it picks the "current node", the first of the two
nodes to swap, it finds the _widest node with the same start point_. `ts_utils` finds the smallest node. This is a subtle difference,
but ends up having a big effect on the intuitiveness of swapping.
[nvim-treesitter.ts_utils](https://github.com/nvim-treesitter/nvim-treesitter/blob/master/lua/nvim-treesitter/ts_utils.lua) - This doesn't
suffer from node name awareness, and works mostly the same as `Treewalker`. Some of `Treewalker`'s left/right swapping code is even
inspired by `ts_utils`. However `Treewalker` offers one fundamental difference - when it picks the "current node", the first of the two
nodes to swap, it finds the _widest node with the same start point_. `ts_utils` finds the smallest node. This is a subtle difference,
but ends up having a big effect on the intuitiveness of swapping.


---
Expand Down

0 comments on commit 1e7e23f

Please sign in to comment.