mirror of
https://github.com/ohmyzsh/ohmyzsh.git
synced 2026-01-23 02:35:38 +01:00
89e0439e21
Adds zsh-vi-man plugin that provides smart man page lookup for zsh vi mode and emacs mode. Press K in vi normal mode, Ctrl-X k in emacs mode, or Ctrl-K in vi insert mode on any command or option to open its man page. Features: - Smart subcommand detection (git commit → man git-commit) - Option jumping (grep -r → jumps to -r entry in man page) - Combined options support (rm -rf → finds both -r and -f) - Pipe support (cat file | grep -i → opens man grep) - Multiple pager support (less, vim, nvim)
112 lines
3.5 KiB
Markdown
112 lines
3.5 KiB
Markdown
# zsh-vi-man plugin
|
|
|
|
Smart man page lookup for zsh vi mode (and emacs mode).
|
|
|
|
Press `K` in vi normal mode, `Ctrl-X k` in emacs mode, or `Ctrl-K` in vi insert mode on any
|
|
command or option to instantly open its man page. If your cursor is on an option (like `-r`
|
|
or `--recursive`), it will jump directly to that option in the man page.
|
|
|
|
To use it, add `zsh-vi-man` to the plugins array in your zshrc file:
|
|
|
|
```zsh
|
|
plugins=(... zsh-vi-man)
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Smart Detection**: Automatically finds the right man page for subcommands
|
|
(`git commit` → `man git-commit`, `docker run` → `man docker-run`)
|
|
- **Option Jumping**: Opens man page directly at the option definition
|
|
(`grep -r` → jumps to `-r` entry)
|
|
- **Combined Options**: Works with combined short options (`rm -rf` → finds both `-r` and `-f`)
|
|
- **Value Extraction**: Handles options with values (`--color=always` → searches `--color`)
|
|
- **Pipe Support**: Detects correct command in pipelines (`cat file | grep -i` → opens `man grep`)
|
|
- **Multiple Formats**: Supports various man page styles (GNU, jq-style, find-style)
|
|
|
|
## Usage
|
|
|
|
### Vi Normal Mode (Default)
|
|
|
|
1. Type a command (e.g., `ls -la` or `git commit --amend`)
|
|
2. Press `Escape` to enter vi normal mode
|
|
3. Move cursor to any word
|
|
4. Press `K` to open the man page
|
|
|
|
### Emacs Mode / Vi Insert Mode
|
|
|
|
Without leaving insert mode or if using emacs mode:
|
|
|
|
- **Emacs mode**: Press `Ctrl-X` then `k`
|
|
- **Vi insert mode**: Press `Ctrl-K`
|
|
|
|
### Examples
|
|
|
|
| Command | Cursor On | Result |
|
|
| :--------------------- | :------------- | :----------------------------------- |
|
|
| `ls -la` | `ls` | Opens `man ls` |
|
|
| `ls -la` | `-la` | Opens `man ls`, jumps to `-l` |
|
|
| `git commit --amend` | `commit` | Opens `man git-commit` |
|
|
| `grep --color=auto` | `--color=auto` | Opens `man grep`, jumps to `--color` |
|
|
| `cat file \| sort -r` | `-r` | Opens `man sort`, jumps to `-r` |
|
|
| `find . -name "*.txt"` | `-name` | Opens `man find`, jumps to `-name` |
|
|
|
|
## Configuration
|
|
|
|
Set these variables **before** Oh My Zsh is sourced:
|
|
|
|
```zsh
|
|
# Vi normal mode key (default: K)
|
|
ZVM_MAN_KEY='?'
|
|
|
|
# Emacs mode key sequence (default: ^Xk, i.e., Ctrl-X k)
|
|
ZVM_MAN_KEY_EMACS='^X^K' # Example: Ctrl-X Ctrl-K
|
|
|
|
# Vi insert mode key (default: ^K, i.e., Ctrl-K)
|
|
ZVM_MAN_KEY_INSERT='^H' # Example: Ctrl-H
|
|
|
|
# Enable/disable emacs mode binding (default: true)
|
|
ZVM_MAN_ENABLE_EMACS=false
|
|
|
|
# Enable/disable vi insert mode binding (default: true)
|
|
ZVM_MAN_ENABLE_INSERT=false
|
|
|
|
# Use a different pager (default: less, supports nvim/vim)
|
|
ZVM_MAN_PAGER='nvim'
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
**Keybindings not working?**
|
|
|
|
If keybindings don't work after sourcing the plugin, try running:
|
|
|
|
```zsh
|
|
zvm_man_rebind
|
|
```
|
|
|
|
This can happen if:
|
|
|
|
- Your plugin manager loads plugins before setting up keymaps
|
|
- You call `bindkey -e` or `bindkey -v` after the plugin loads
|
|
- Another plugin resets your keybindings
|
|
|
|
For persistent issues, add this to your `.zshrc` **after** sourcing Oh My Zsh:
|
|
|
|
```zsh
|
|
# Ensure zsh-vi-man bindings are set
|
|
zvm_man_rebind
|
|
```
|
|
|
|
## Integration with zsh-vi-mode
|
|
|
|
This plugin works seamlessly with [zsh-vi-mode](https://github.com/jeffreytse/zsh-vi-mode).
|
|
It automatically detects zsh-vi-mode and hooks into its lazy keybindings system.
|
|
|
|
## Author
|
|
|
|
- [Tuna Cuma](https://github.com/TunaCuma)
|
|
|
|
## License
|
|
|
|
MIT License - see [LICENSE](https://github.com/TunaCuma/zsh-vi-man/blob/main/LICENSE) for details.
|
|
|