Stevan/watchexec.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: cleanup

Browse Source
This commit is contained in:
Stevan Freeborn
2026-07-06 20:07:44 -05:00
parent 8bbc045485
commit 0434637a12
2 changed files with 68 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.vscode/settings.json
Vendored
+10
View File
@@ -0,0 +1,10 @@
{
"cSpell.words": [
"guibg",
"Keymap",
"Keymaps",
"nvim",
"stevanfreeborn",
"watchexec"
]
}
README.md
+58 -57
View File
@@ -7,15 +7,12 @@ split window.
## Features ## Features
- **Floating or split** output window, configurable per-user. - **Floating or split** output window, configurable per-user.
- **Status indicator** — a small non-focusable float that shows success or - **Status indicator** — a small non-focusable float that shows success or failure when the main window is hidden.
failure when the main window is hidden.
- **ANSI escape sequence stripping** so output is clean. - **ANSI escape sequence stripping** so output is clean.
- **Keyword highlighting** via `DiagnosticError`, `DiagnosticWarn`, and - **Keyword highlighting** via `DiagnosticError`, `DiagnosticWarn`, and `DiagnosticOk` for error/warning/success keywords in output.
`DiagnosticOk` for error/warning/success keywords in output.
- **Auto-scroll** to the latest output, with configurable buffer size limits. - **Auto-scroll** to the latest output, with configurable buffer size limits.
- **Auto-resize** on `VimResized`, and automatic cleanup on `VimLeavePre`. - **Auto-resize** on `VimResized`, and automatic cleanup on `VimLeavePre`.
- **Binary auto-discovery** — searches PATH, `~/.cargo/bin`, Homebrew, and - **Binary auto-discovery** — searches PATH, `~/.cargo/bin`, Homebrew, and WSL locations.
WSL locations.
## Requirements ## Requirements
@@ -24,7 +21,7 @@ split window.
Install the CLI: Install the CLI:
``` ```pwsh
cargo install watchexec cargo install watchexec
``` ```
@@ -32,7 +29,8 @@ Or download a prebuilt binary from the [releases page](https://github.com/watche
## Installation ## Installation
**lazy.nvim** ### lazy.nvim
```lua ```lua
{ {
"stevanfreeborn/watchexec.nvim", "stevanfreeborn/watchexec.nvim",
@@ -40,7 +38,8 @@ Or download a prebuilt binary from the [releases page](https://github.com/watche
} }
``` ```
**packer.nvim** ### packer.nvim
```lua ```lua
use { use {
"stevanfreeborn/watchexec.nvim", "stevanfreeborn/watchexec.nvim",
@@ -50,7 +49,8 @@ use {
} }
``` ```
**vim-plug** ### vim-plug
```vim ```vim
Plug 'stevanfreeborn/watchexec.nvim' Plug 'stevanfreeborn/watchexec.nvim'
lua require("watchexec").setup({}) lua require("watchexec").setup({})
@@ -60,7 +60,7 @@ lua require("watchexec").setup({})
After installing, restart Neovim and run: After installing, restart Neovim and run:
``` ```txt
:WatchexecRun echo hello :WatchexecRun echo hello
``` ```
@@ -75,55 +75,55 @@ to close it. Press `<Leader>wxt` to toggle it back.
### `watchexec` — binary options ### `watchexec` — binary options
| Field | Type | Default | Description | | Field | Type | Default | Description |
|---------|----------|------------------|-------------| |--------|----------|---------------|---------------------------------------------------------------------------------|
| `bin` | `string` | `"watchexec"` | Path to the watchexec executable. Auto-detected from PATH and common locations. | | `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. | | `args` | `table` | `{}` | Extra arguments passed to watchexec before the user command. |
### `window` — output window options ### `window` — output window options
| Field | Type | Default | Description | | Field | Type | Default | Description |
|----------|----------------------|--------------|-------------| |----------|----------------------------------------------|---------------|--------------------------------------------------------|
| `type` | `"float"` / `"split"` | `"float"` | Window type. | | `type` | `"float"` / `"split"` | `"float"` | Window type. |
| `split` | `"below"` / `"above"` / `"left"` / `"right"` | `"below"` | Split direction (only used when `type` is `"split"`). | | `split` | `"below"` / `"above"` / `"left"` / `"right"` | `"below"` | Split direction (only used when `type` is `"split"`). |
| `size` | `integer` | `12` | Split window size in rows/columns. | | `size` | `integer` | `12` | Split window size in rows/columns. |
| `border` | `string` / `table` | `"single"` | Border style for floats (see `:help nvim_open_win()`). | | `border` | `string` / `table` | `"single"` | Border style for floats (see `:help nvim_open_win()`). |
| `float` | `table` | *(see below)* | Float geometry. | | `float` | `table` | *(see below)* | Float geometry. |
#### `window.float` — float geometry #### `window.float` — float geometry
| Field | Type | Default | Description | | Field | Type | Default | Description |
|------------|----------|--------------|-------------| |------------|----------|------------|---------------------------------------------------------------|
| `relative` | `string` | `"editor"` | Positioning anchor. | | `relative` | `string` | `"editor"` | Positioning anchor. |
| `width` | `number` | `0.8` | Width in columns (values <= 1 are fractions of editor width). | | `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). | | `height` | `number` | `0.6` | Height in rows (values <= 1 are fractions of editor height). |
| `row` | `number` | `0.5` | Row position (values <= 1 are fractions). | | `row` | `number` | `0.5` | Row position (values <= 1 are fractions). |
| `col` | `number` | `0.5` | Column position (values <= 1 are fractions). | | `col` | `number` | `0.5` | Column position (values <= 1 are fractions). |
### `indicator` — status indicator options ### `indicator` — status indicator options
| Field | Type | Default | Description | | Field | Type | Default | Description |
|--------------|-----------------------------------------------|---------------------|-------------| |--------------|-------------------------------------------------------------------|----------------------|----------------------------------|
| `enabled` | `boolean` | `true` | Enable/disable the indicator. | | `enabled` | `boolean` | `true` | Enable/disable the indicator. |
| `position` | `"bottom-left"` / `"bottom-right"` / `"top-left"` / `"top-right"` | `"bottom-right"` | Screen corner. | | `position` | `"bottom-left"` / `"bottom-right"` / `"top-left"` / `"top-right"` | `"bottom-right"` | Screen corner. |
| `success_hl` | `string` | `"WatchexecSuccess"` | Highlight for success state. | | `success_hl` | `string` | `"WatchexecSuccess"` | Highlight for success state. |
| `failure_hl` | `string` | `"WatchexecFailure"` | Highlight for failure state. | | `failure_hl` | `string` | `"WatchexecFailure"` | Highlight for failure state. |
| `width` | `integer` | `2` | Indicator width in cells. | | `width` | `integer` | `2` | Indicator width in cells. |
| `height` | `integer` | `1` | Indicator height in cells. | | `height` | `integer` | `1` | Indicator height in cells. |
| `patterns` | `table` | *(see below)* | Lua patterns for parsing output. | | `patterns` | `table` | *(see below)* | Lua patterns for parsing output. |
#### `indicator.patterns` #### `indicator.patterns`
| Field | Type | Default | Description | | Field | Type | Default | Description |
|-----------|----------|-----------------------------|-------------| |-----------|----------|--------------------------------|---------------------------------------------|
| `success` | `string` | `"%[Command was successful%]"` | Pattern matching successful command output. | | `success` | `string` | `"%[Command was successful%]"` | Pattern matching successful command output. |
| `running` | `string` | `"%[Running"` | Pattern matching command start. | | `running` | `string` | `"%[Running"` | Pattern matching command start. |
### General options ### General options
| Field | Type | Default | Description | | Field | Type | Default | Description |
|---------------|-----------|---------|-------------| |---------------|-----------|---------|------------------------------------------------------|
| `auto_scroll` | `boolean` | `true` | Scroll to bottom on new output. | | `auto_scroll` | `boolean` | `true` | Scroll to bottom on new output. |
| `max_lines` | `integer` | `5000` | Maximum lines in the output buffer (oldest trimmed). | | `max_lines` | `integer` | `5000` | Maximum lines in the output buffer (oldest trimmed). |
### Full config example ### Full config example
@@ -150,28 +150,29 @@ require("watchexec").setup({
## Commands ## Commands
| Command | Description | | Command | Description |
|---------|-------------| |---------------------------|---------------------------------------------------------------------------------------------------|
| `:WatchexecRun {command}` | Start watchexec with the given shell command. Stops any previous run and opens the output window. | | `: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. | | `:WatchexecStop` | Stop the currently running watchexec process and clear the output. |
| `:WatchexecToggle` | Toggle the output window. | | `:WatchexecToggle` | Toggle the output window. |
## Keymaps ## Keymaps
| Keymap | Action | Description | | Keymap | Action | Description |
|----------------|--------|-------------| |---------------|--------------------|----------------------------------|
| `<Leader>wxt` | `:WatchexecToggle` | Toggle the output window. | | `<Leader>wxt` | `:WatchexecToggle` | Toggle the output window. |
| `<Leader>wxs` | `:WatchexecStop` | Stop the running process. | | `<Leader>wxs` | `:WatchexecStop` | Stop the running process. |
| `<Leader>wxr` | `:WatchexecRun` | Prompt for a command and run it. | | `<Leader>wxr` | `:WatchexecRun` | Prompt for a command and run it. |
## Highlight Groups ## Highlight Groups
| Group | Default | Description | | Group | Default | Description |
|-------|---------|-------------| |--------------------|-----------------|-------------------------------------------------------|
| `WatchexecSuccess` | `guibg=#00ff00` | Indicator background when the last command succeeded. | | `WatchexecSuccess` | `guibg=#00ff00` | Indicator background when the last command succeeded. |
| `WatchexecFailure` | `guibg=#ff0000` | Indicator background when the last command failed. | | `WatchexecFailure` | `guibg=#ff0000` | Indicator background when the last command failed. |
Output lines are also highlighted using built-in diagnostic groups: Output lines are also highlighted using built-in diagnostic groups:
- `DiagnosticError` — for error, fail, fatal keywords - `DiagnosticError` — for error, fail, fatal keywords
- `DiagnosticWarn` — for warning keywords - `DiagnosticWarn` — for warning keywords
- `DiagnosticOk` — for success, passed, ok keywords - `DiagnosticOk` — for success, passed, ok keywords
@@ -194,7 +195,7 @@ require("watchexec").toggle()
Full help is available in Neovim: Full help is available in Neovim:
``` ```txt
:help watchexec :help watchexec
``` ```