docs: add comprehensive README
Replace the placeholder README with a full reference covering features, requirements, installation (lazy/packer/vim-plug), configuration tables with defaults, commands, keymaps, highlight groups, API, and a quick start guide.
This commit is contained in:
Stevan Freeborn
@@ -1,3 +1,203 @@
|
||||
# watchexec.nvim
|
||||
|
||||
This plugin allows you to start and stop a task using watchexec and display the output of the task within Neovim.
|
||||
Integrate the [watchexec](https://github.com/watchexec/watchexec) CLI into
|
||||
Neovim — run file-watching commands and view their output in a floating or
|
||||
split window.
|
||||
|
||||
## Features
|
||||
|
||||
- **Floating or split** output window, configurable per-user.
|
||||
- **Status indicator** — a small non-focusable float that shows success or
|
||||
failure when the main window is hidden.
|
||||
- **ANSI escape sequence stripping** so output is clean.
|
||||
- **Keyword highlighting** via `DiagnosticError`, `DiagnosticWarn`, and
|
||||
`DiagnosticOk` for error/warning/success keywords in output.
|
||||
- **Auto-scroll** to the latest output, with configurable buffer size limits.
|
||||
- **Auto-resize** on `VimResized`, and automatic cleanup on `VimLeavePre`.
|
||||
- **Binary auto-discovery** — searches PATH, `~/.cargo/bin`, Homebrew, and
|
||||
WSL locations.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Neovim >= 0.10
|
||||
- [watchexec CLI](https://github.com/watchexec/watchexec)
|
||||
|
||||
Install the CLI:
|
||||
|
||||
```
|
||||
cargo install watchexec
|
||||
```
|
||||
|
||||
Or download a prebuilt binary from the [releases page](https://github.com/watchexec/watchexec/releases).
|
||||
|
||||
## Installation
|
||||
|
||||
**lazy.nvim**
|
||||
```lua
|
||||
{
|
||||
"stevanfreeborn/watchexec.nvim",
|
||||
opts = {},
|
||||
}
|
||||
```
|
||||
|
||||
**packer.nvim**
|
||||
```lua
|
||||
use {
|
||||
"stevanfreeborn/watchexec.nvim",
|
||||
config = function()
|
||||
require("watchexec").setup({})
|
||||
end,
|
||||
}
|
||||
```
|
||||
|
||||
**vim-plug**
|
||||
```vim
|
||||
Plug 'stevanfreeborn/watchexec.nvim'
|
||||
lua require("watchexec").setup({})
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
After installing, restart Neovim and run:
|
||||
|
||||
```
|
||||
:WatchexecRun echo hello
|
||||
```
|
||||
|
||||
Or press `<Leader>wxr`, type a command at the prompt, and press Enter.
|
||||
|
||||
The output window opens automatically. Press `q` or `<Esc>` inside the window
|
||||
to close it. Press `<Leader>wxt` to toggle it back.
|
||||
|
||||
## Configuration
|
||||
|
||||
`setup()` accepts an optional table with the following fields:
|
||||
|
||||
### `watchexec` — binary options
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---------|----------|------------------|-------------|
|
||||
| `bin` | `string` | `"watchexec"` | Path to the watchexec executable. Auto-detected from PATH and common locations. |
|
||||
| `args` | `table` | `{}` | Extra arguments passed to watchexec before the user command. |
|
||||
|
||||
### `window` — output window options
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|----------|----------------------|--------------|-------------|
|
||||
| `type` | `"float"` / `"split"` | `"float"` | Window type. |
|
||||
| `split` | `"below"` / `"above"` / `"left"` / `"right"` | `"below"` | Split direction (only used when `type` is `"split"`). |
|
||||
| `size` | `integer` | `12` | Split window size in rows/columns. |
|
||||
| `border` | `string` / `table` | `"single"` | Border style for floats (see `:help nvim_open_win()`). |
|
||||
| `float` | `table` | *(see below)* | Float geometry. |
|
||||
|
||||
#### `window.float` — float geometry
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|------------|----------|--------------|-------------|
|
||||
| `relative` | `string` | `"editor"` | Positioning anchor. |
|
||||
| `width` | `number` | `0.8` | Width in columns (values <= 1 are fractions of editor width). |
|
||||
| `height` | `number` | `0.6` | Height in rows (values <= 1 are fractions of editor height). |
|
||||
| `row` | `number` | `0.5` | Row position (values <= 1 are fractions). |
|
||||
| `col` | `number` | `0.5` | Column position (values <= 1 are fractions). |
|
||||
|
||||
### `indicator` — status indicator options
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|--------------|-----------------------------------------------|---------------------|-------------|
|
||||
| `enabled` | `boolean` | `true` | Enable/disable the indicator. |
|
||||
| `position` | `"bottom-left"` / `"bottom-right"` / `"top-left"` / `"top-right"` | `"bottom-right"` | Screen corner. |
|
||||
| `success_hl` | `string` | `"WatchexecSuccess"` | Highlight for success state. |
|
||||
| `failure_hl` | `string` | `"WatchexecFailure"` | Highlight for failure state. |
|
||||
| `width` | `integer` | `2` | Indicator width in cells. |
|
||||
| `height` | `integer` | `1` | Indicator height in cells. |
|
||||
| `patterns` | `table` | *(see below)* | Lua patterns for parsing output. |
|
||||
|
||||
#### `indicator.patterns`
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-----------|----------|-----------------------------|-------------|
|
||||
| `success` | `string` | `"%[Command was successful%]"` | Pattern matching successful command output. |
|
||||
| `running` | `string` | `"%[Running"` | Pattern matching command start. |
|
||||
|
||||
### General options
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---------------|-----------|---------|-------------|
|
||||
| `auto_scroll` | `boolean` | `true` | Scroll to bottom on new output. |
|
||||
| `max_lines` | `integer` | `5000` | Maximum lines in the output buffer (oldest trimmed). |
|
||||
|
||||
### Full config example
|
||||
|
||||
```lua
|
||||
require("watchexec").setup({
|
||||
auto_scroll = false,
|
||||
max_lines = 1000,
|
||||
watchexec = {
|
||||
bin = "watchexec",
|
||||
args = { "--shell", "bash" },
|
||||
},
|
||||
window = {
|
||||
type = "split",
|
||||
split = "below",
|
||||
size = 15,
|
||||
},
|
||||
indicator = {
|
||||
enabled = true,
|
||||
position = "bottom-left",
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `:WatchexecRun {command}` | Start watchexec with the given shell command. Stops any previous run and opens the output window. |
|
||||
| `:WatchexecStop` | Stop the currently running watchexec process and clear the output. |
|
||||
| `:WatchexecToggle` | Toggle the output window. |
|
||||
|
||||
## Keymaps
|
||||
|
||||
| Keymap | Action | Description |
|
||||
|----------------|--------|-------------|
|
||||
| `<Leader>wxt` | `:WatchexecToggle` | Toggle the output window. |
|
||||
| `<Leader>wxs` | `:WatchexecStop` | Stop the running process. |
|
||||
| `<Leader>wxr` | `:WatchexecRun` | Prompt for a command and run it. |
|
||||
|
||||
## Highlight Groups
|
||||
|
||||
| Group | Default | Description |
|
||||
|-------|---------|-------------|
|
||||
| `WatchexecSuccess` | `guibg=#00ff00` | Indicator background when the last command succeeded. |
|
||||
| `WatchexecFailure` | `guibg=#ff0000` | Indicator background when the last command failed. |
|
||||
|
||||
Output lines are also highlighted using built-in diagnostic groups:
|
||||
- `DiagnosticError` — for error, fail, fatal keywords
|
||||
- `DiagnosticWarn` — for warning keywords
|
||||
- `DiagnosticOk` — for success, passed, ok keywords
|
||||
|
||||
## API
|
||||
|
||||
```lua
|
||||
---@param opts? watchexec.Config
|
||||
require("watchexec").setup(opts)
|
||||
|
||||
---@param command string
|
||||
require("watchexec").run(command)
|
||||
|
||||
require("watchexec").stop()
|
||||
|
||||
require("watchexec").toggle()
|
||||
```
|
||||
|
||||
## Documentation
|
||||
|
||||
Full help is available in Neovim:
|
||||
|
||||
```
|
||||
:help watchexec
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user