import-ohmyzsh-plugins — Oh-My-Zsh Plugin Importer¶
Import and manage Oh-My-Zsh compatible plugins for ZSHAND.
Synopsis¶
import-ohmyzsh-plugins [OPTIONS] [PLUGIN...]
```bash
## Description
Interactive tool for importing Oh-My-Zsh plugins into your ZSHAND config.
Copies plugin source files to `~/.config/zshand/plugins/` with proper load
order prefixes and generates `plugins.txt` for configuration.
## Options
| Option | Description |
| ------------------- | ------------------------------------------------ |
| `-a`, `--all` | Import all essential plugins + generate files |
| `-l`, `--list` | List available plugins |
| `-t`, `--theme` | Import an OMZ theme (e.g., agnoster, robbyrussell) |
| `--list-themes` | List available OMZ themes |
| `-f`, `--force` | Force reimport (overwrite existing) |
| `-n`, `--dry-run` | Show what would be done without making changes |
| `--force-unsafe` | Import blocked/redundant plugins anyway |
| `-h`, `--help` | Show help message |
## Plugin Load Order Prefixes
| Prefix | Category | Description |
| ------- | -------------- | ---------------------------------------- |
| `00-09` | Immediate Early| Infrastructure (omz-compat, shared-deps) |
| `10-89` | Deferred | Normal plugins (load after prompt) |
| `90-99` | Immediate Late | Syntax highlighting (must load last) |
## Essential Plugins
These are imported with `--all`:
| Plugin | Prefix | Description |
| ------------------------- | ------ | ------------------------------------- |
| `you-should-use` | 10 | Reminds you of existing aliases |
| `zsh-autosuggestions` | 50 | Fish-like autosuggestions |
| `zsh-syntax-highlighting` | 98-99 | Syntax highlighting (2 files) |
## Plugin Compatibility
The importer checks plugins for compatibility:
| Status | Code | Description |
| ----------- | ---- | ---------------------------------------------- |
| compatible | 0 | Works as-is |
| blocked | 1 | Needs full OMZ structure, won't import |
| fixable | 2 | Auto-fixes by bundling required libs |
| redundant | 3 | ZSHAND already provides this feature |
### Redundant Plugins
These are already provided by ZSHAND:
| Plugin | Reason |
| ------ | ---------------------------------------------------- |
| `git` | `core/14_aliases.zsh` provides git aliases (g, ga, etc) |
### Blocked Plugins
These require full OMZ and won't import:
| Plugin | Reason |
| -------- | ----------------------------------------- |
| `catimg` | Uses `$ZSH/plugins/catimg/catimg.sh` |
### Fixable Plugins
These need lib files that are auto-bundled:
| Plugin | Auto-bundled File |
| ---------- | ----------------- |
| `gitfast` | `lib/git.zsh` |
| `git-flow` | `lib/git.zsh` |
| `git-lfs` | `lib/git.zsh` |
## Examples
```bash
# Interactive selection
import-ohmyzsh-plugins
# Import essential plugins
import-ohmyzsh-plugins --all
# List available plugins
import-ohmyzsh-plugins --list
# Import specific plugins
import-ohmyzsh-plugins zsh-z zsh-autosuggestions
# Force reimport all
import-ohmyzsh-plugins --all --force
# Dry-run to see what would happen
import-ohmyzsh-plugins --all --dry-run
# Import a redundant plugin anyway
import-ohmyzsh-plugins --force-unsafe git
# List available OMZ themes
import-ohmyzsh-plugins --list-themes
# Import an OMZ theme
import-ohmyzsh-plugins --theme agnoster
# Import theme with git.zsh dependency
import-ohmyzsh-plugins --theme robbyrussell
```bash
## Generated Files
| File | Purpose |
| ----------------------------------- | ------------------------------------ |
| `~/.config/zshand/plugins.txt` | Plugin load order configuration |
| `~/.config/zshand/plugins/*.zsh` | Plugin source files |
| `00-omz-compat.zsh` | OMZ compatibility shim |
| `01-shared-deps.zsh` | Shared autoloads/zmodloads |
| `02-omz-lib-*.zsh` | Bundled OMZ lib files (if needed) |
| `02-omz-theme-stubs.zsh` | Stub functions for themes |
| `03-omz-theme-*.zsh` | Imported OMZ theme file |
| `98-zsh-syntax-highlighting-main.zsh` | Syntax highlighter functions |
| `99-zsh-syntax-highlighting.zsh` | Syntax highlighting loader |
## OMZ Themes
Use `ZSHAND_OMZ_THEME` to use an OMZ theme instead of Powerlevel10k:
```zsh
# In ~/.config/zshand/env.zsh
export ZSHAND_OMZ_THEME=agnoster
```bash
### Self-contained Themes (no dependencies)
These work immediately:
- `agnoster` — Popular powerline-style theme
- `candy` — Colorful minimal theme
- `avit` — Clean minimal theme
- `emotty` — Emoji-based theme
### Themes Needing git.zsh
Most themes need `git_prompt_info()` from `lib/git.zsh` — auto-bundled:
- `robbyrussell` — The classic OMZ default
- `bira`, `bureau`, `fino`, `gnzh`, `jonathan`, `kafeitu`, `lambda`
- `mh`, `philips`, `simple`, `sorin`, `steeef`, `ys`
### Theme Stub Functions
For themes needing `ruby_prompt_info`, `virtualenv_prompt_info`, etc.,
the importer creates `02-omz-theme-stubs.zsh` with stub implementations.
## plugins.txt Format
```bash
# LOAD TIMING:
# (none) = Immediate - blocks startup
# ~ = Lazy - loads after first prompt
# + = Deferred - 0.1s delay (fastest feel)
# - = Disabled
# IMMEDIATE EARLY
omz-compat
shared-deps
# DEFERRED
+ you-should-use
+ zsh-autosuggestions
# IMMEDIATE LATE
zsh-syntax-highlighting-main
zsh-syntax-highlighting
```bash
## Plugin Sources
The importer searches for plugins in:
1. `/usr/share/zsh/plugins/` — System packages
2. `~/.oh-my-zsh/custom/plugins/` — OMZ custom
3. `~/.oh-my-zsh/plugins/` — OMZ bundled
4. `~/.local/share/zsh/plugins/` — User-installed
## OMZ Compatibility Shim
The `00-omz-compat.zsh` provides OMZ variables and functions:
```zsh
ZSH="$HOME/.oh-my-zsh"
ZSH_CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/zsh"
# Functions
is-at-least() { ... }
omz_urlencode() { ... }
env_default() { ... }
open_command() { ... }
```bash
## See Also
- [`samples/user-config/plugins/README.md`](../../samples/user-config/plugins/README.md) — Plugin directory docs
- [`import-p10k-theme`](import-p10k-theme.md) — P10k theme importer
- [`core/20_plugins.zsh`](../../core/20_plugins.zsh) — Plugin loader