// ZSH-GEM-COMPLETION — LIVE REMOTE GEM COMPLETION FOR gem install

Overview

zsh-gem-completion is a single #compdef gem completion (src/_gem) plus a small plugin entrypoint (zsh-gem-completion.plugin.zsh). It started from the Homebrew/OMZ gem completion and adds one behavior the upstream lacks: gem install <TAB> completes remote gems from the live output of gem search, not just gems already installed locally.

• 30 subcommands with one-line man-page descriptions, offered when you type gem <TAB>.
• Remote completion for install — __gem_search shells out to gem search -q $PREFIX and renders the rubygems.org results with descriptions.
• Local completion for uninstall / update / list — __gem_installed reads gem list --local --no-versions.
• File completion for build — _files -g "*.gemspec", glob-restricted to gemspecs.
• Two-tier cache — an in-shell array (__gems_${PREFIX}) and the on-disk _store_cache / _retrieve_cache store keyed gem_${PREFIX}_cache.
• 3 publishing shortcuts — gemb, gemp, and the gemy function for the gem-author build/push/yank loop.

Requires zsh, the zsh completion system (compinit), and the gem command on $PATH. The remote-search path additionally relies on gem search reaching rubygems.org.

Install

# Zinit
zinit ice lucid nocompile
zinit load MenkeTechnologies/zsh-gem-completion

# Oh My Zsh
git clone https://github.com/MenkeTechnologies/zsh-gem-completion \
    "$HOME/.oh-my-zsh/custom/plugins/zsh-gem-completion"
# then: plugins+=(zsh-gem-completion)

# Manual
git clone https://github.com/MenkeTechnologies/zsh-gem-completion
source zsh-gem-completion/zsh-gem-completion.plugin.zsh

Examples

gem <TAB>                # subcommand completion (30 entries, with descriptions)
gem install <TAB>        # live remote gem name completion via `gem search`
gem install ra<TAB>      # remote search for the `ra` prefix: rails, rack, rake, ...
gem uninstall <TAB>      # locally-installed gems only (gem list --local --no-versions)
gem update <TAB>         # locally-installed gems only
gem list <TAB>           # locally-installed gems (in the `forms` state)
gem build <TAB>          # *.gemspec files in the current directory

gemb                    # gem build *.gemspec
gemp                    # gem push *.gem
gemy my-gem 1.2.3       # gem yank my-gem -v 1.2.3

First TAB on a remote prefix pays one gem search network round-trip; subsequent TABs for the same prefix are served from cache — the in-shell array within the session, and the on-disk store across sessions.

Subcommand reference

Every entry in _1st_arguments (src/_gem), offered on gem <TAB>. Descriptions are the exact strings shown in the completion menu.

Top-level flags, offered before a subcommand is chosen: -v/--version (show version) and -h/--help (show help), each declared mutually-exclusive with its long form.

Completion behavior

After the top-level _arguments dispatch, src/_gem branches per first word. Only these subcommands have argument completion wired; the rest complete the subcommand name only.

Remote-search parse + quoting: each line of gem search output is read as tag desc (gem name, then the remainder of the line), then stored as ${(q)tag}:${(q)desc}. The (q) flag backslash-quotes both halves so colons or spaces in the name/version don't mis-split zsh's name:description tuple. __gem_search is the active dispatcher; __gem_search_mem is the in-shell-array variant kept in the source as the session-cache implementation.

Aliases & functions

Registered by zsh-gem-completion.plugin.zsh for the gem-author build/push/yank loop:

Configuration

The completion sets one zstyle in src/_gem:

zstyle ':completion:*:*:gem:*:remote-gem' list-grouped false

This scopes only the remote-search results (the remote-gem tag) and turns off description-grouping, so each remote gem renders on its own row. The local gem list path is untouched and keeps the default grouping. You can override completion presentation with your own zstyle lines after the plugin loads; the entrypoint also prepends src/ to fpath so compinit can autoload _gem.

Troubleshooting

Engineering report

For the file-by-file breakdown, completion-coverage matrix, test inventory, and design-decision notes, see the Engineering Report.

Sibling plugins

Part of the MenkeTechnologies zsh plugin family — the MenkeTechnologiesMeta umbrella:

• zsh-better-npm-completion — cache-aware npm install completion
• zsh-cargo-completion — live cargo add / cargo install completion
• zsh-cpan-completion — live MetaCPAN cpan / cpanm completion
• zsh-dotnet-completion — dotnet CLI completion
• zsh-expand — spacebar expansion (11,683 tests)
• zsh-git-acp — 159 git aliases + add/commit/push keybindings
• zsh-git-repo-cache — index every git repo on disk
• zsh-learn — MySQL-backed learning collection / quiz
• zsh-more-completions — 33,175-file mega completion corpus
• zsh-nginx — nginx commands + service-wrapper aliases
• zsh-pip-description-completion — pip remote completion with descriptions
• zsh-sed-sub — in-place sed substitution on the command line
• zsh-sudo — ESC ESC to prepend sudo
• zsh-xcode-completions — xcodebuild / xcrun / swift completion