zsh-smart-insert

April 20, 2025 · View on GitHub

Smart file search and insertion for Zsh ✨
Insert file paths from fuzzy search directly into your command line.

🔍 About

zsh-smart-insert is a Zsh plugin that provides interactive widgets to search for files and content using fd, rg, and fzf. It inserts the result directly into your shell with optional command prefixes.

📂 File path selection with preview via fd + fzf
🧠 Content search with reactive reload using ripgrep
⌨️ Prefix support (e.g. vim, cat, less, code)
🎨 Syntax-highlighted preview using bat

⚙️ Requirements

Tool	Purpose	Link
`fzf`	Interactive fuzzy search	Link
`fd`	File system search	Link
`rg`	Content search engine	Link
`bat`	Preview with syntax highlighting	Link

🚀 Installation

Manual

git clone https://github.com/lgdevlop/zsh-smart-insert.git ~/.zsh-smart-insert
echo "source ~/.zsh-smart-insert/zsh-smart-insert.plugin.zsh" >> ~/.zshrc
source ~/.zshrc

Zinit

zinit light lgdevlop/zsh-smart-insert

Antigen

antigen bundle lgdevlop/zsh-smart-insert

Oh My Zsh (manual plugin)

git clone https://github.com/lgdevlop/zsh-smart-insert.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-smart-insert

Then add to your .zshrc:

plugins=(git zsh-smart-insert)

Reload with:

omz reload   # if using Oh My Zsh
# or
source ~/.zshrc

💡 Usage

Alt+f – Pick files by name with fd
Alt+g – Search files by name with rg
Alt+s – Search file content with live reload

Each result is inserted at the cursor with an optional prefix.

Example: Select a file with vim as prefix → inserts vim ./my/file.txt

More examples in project-docs/examples.md

🧩 Configuration

You can customize behavior with environment variables:

# Custom prefix options (fzf menu)
export ZSH_SMART_INSERT_PREFIXES="nvim:less:code"

# Custom directories to ignore in fd/rg
export ZSH_SMART_INSERT_IGNOREDIRS=".git/*:node_modules/:dist/:.venv/"

⌨️ Shortcuts

Key	Action
`Alt+f`	Fuzzy file picker with preview
`Alt+g`	File name search with `rg`
`Alt+s`	Content search with live reload
`Ctrl+/`	Toggle preview in FZF

See project-docs/shortcuts.md for full reference.

📁 Project Structure

.
├── zsh-smart-insert.plugin.zsh     # Plugin entry point
├── functions/                      # Reusable Zsh helpers
├── internal/                       # ZLE widgets (fzf search)
├── scripts/                        # Automation (e.g. release notes)
├── project-docs/                   # Docs: shortcuts, examples
├── .github/workflows/              # CI/CD pipelines
├── install.sh                      # Interactive installer

🛣️ Roadmap

Prefix selector with command injection
Search by name and content
Interactive previews with bat
Customizable prefixes and ignored paths
Per-widget user customization (e.g. ignoredir by mode)
Custom themes and per-widget configuration

🤝 Contributing

Contributions are welcome! Open an issue or submit a pull request.

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

📄 License

MIT — See LICENSE.

👤 Author

Made with ❤️ by Leonardo Gomes

✨ zsh-smart-insert — Insert smarter, search faster!