https://github.com/tunacuma/zsh-vi-man
Zsh vi-mode plugin for instant man-page help — press Shift-K to open a command’s man page with the option under your cursor auto-searched. 🔍
https://github.com/tunacuma/zsh-vi-man
antigen command-line-tool man-page oh-my-zsh productivity shell shell-script terminal vi-keybinds vim zgen zinit zplug zsh zsh-plugin zsh-plugins
Last synced: about 1 month ago
JSON representation
Zsh vi-mode plugin for instant man-page help — press Shift-K to open a command’s man page with the option under your cursor auto-searched. 🔍
- Host: GitHub
- URL: https://github.com/tunacuma/zsh-vi-man
- Owner: TunaCuma
- License: mit
- Created: 2025-11-26T21:11:24.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-11-27T19:18:55.000Z (about 1 month ago)
- Last Synced: 2025-11-29T16:55:08.426Z (about 1 month ago)
- Topics: antigen, command-line-tool, man-page, oh-my-zsh, productivity, shell, shell-script, terminal, vi-keybinds, vim, zgen, zinit, zplug, zsh, zsh-plugin, zsh-plugins
- Language: Shell
- Homepage:
- Size: 2.7 MB
- Stars: 58
- Watchers: 0
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📖 zsh-vi-man
**Smart man page lookup for zsh vi mode**
Press `Shift-K` on any command or option to instantly open its man page
[](LICENSE)
[](https://www.zsh.org/)
## ✨ 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
ls --color → jumps to --color entry
```
### 🔗 Combined Options
Works with combined short options
```
rm -rf → finds both -r and -f
tar -xvf → finds -x, -v, -f
```
### 📝 Value Extraction
Handles options with values
```
--color=always → searches --color
--output=file.txt → searches --output
```
### 🔀 Pipe Support
Detects correct command in pipelines
```
cat file | grep -i → opens man grep
tree | less -N → opens man less
```
### 🛠️ Multiple Formats
Supports various man page styles
```
GNU: -R, -r, --recursive
jq: --slurp / -s:
find: -name, -type, -exec
```
## 📦 Installation
zinit
```zsh
zinit light TunaCuma/zsh-vi-man
```
antidote
Add to your `.zsh_plugins.txt`:
```
TunaCuma/zsh-vi-man
```
oh-my-zsh
```bash
git clone https://github.com/TunaCuma/zsh-vi-man \
${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-vi-man
```
Then add to your `.zshrc`:
```zsh
plugins=(... zsh-vi-man)
```
Manual
```bash
git clone https://github.com/TunaCuma/zsh-vi-man ~/.zsh-vi-man
echo 'source ~/.zsh-vi-man/zsh-vi-man.plugin.zsh' >> ~/.zshrc
```
## 🚀 Usage
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
### 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** sourcing the plugin:
```zsh
# Change the trigger key (default: K)
ZVM_MAN_KEY='?'
# Use a different pager (default: less)
ZVM_MAN_PAGER='bat'
```
## 🔌 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.
For best results, source this plugin **after** zsh-vi-mode:
```zsh
source /path/to/zsh-vi-mode.zsh
source /path/to/zsh-vi-man.zsh
```
## 📄 License
MIT License - see [LICENSE](LICENSE) for details.
---
Made with ❤️ by [Tuna Cuma](https://github.com/TunaCuma)