zsh-abbr-plugin

June 5, 2026 · View on GitHub

zsh-abbr-plugin

Type less. Ship more.

Lightweight abbreviation expansion for zsh — inspired by fish, built for speed.

License: MIT zsh

Quick start

# Load the plugin
source /path/to/zsh-abbr-plugin/abbr.plugin.zsh

# Add abbreviations
zabbr add gc  'git commit'
zabbr add gp  'git push'
zabbr add -g G '| grep'

# Type away
gc  ──▶ git commit
gp G ──▶ git push | grep

Expansion happens automatically on space and Enter. Want a manual trigger? Bind it:

bindkey '^X ' zabbr-expand   # Ctrl-X Space

Features

Two scopesregular (command position) and global (any position)
Project-localDrop a .abbrs file in your repo — definitions follow cd
PersistentUser abbreviations saved to ~/.zsh-abbr, not your .zshrc
Zero configSource the plugin and go
SafeQuoted tokens, escapes, and $var are never expanded

Commands

zabbr add [-g|--global] NAME EXPANSION   Add abbreviation
zabbr list                               List all abbreviations
zabbr unset NAME                         Remove abbreviation
zabbr reload                             Reload user + project files
zabbr help [COMMAND]                     Show help

zabbr with no arguments is zabbr list.

Abbreviation scopes

regular — command position only

zabbr add gc 'git commit'

❯ gc<space>        ──▶  ❯ git commit _

Only expands as the first word of a simple command (after assignments, precommands, redirects, etc.).

global — any position

zabbr add -g G '| grep'

❯ cat log G<space> ──▶  ❯ cat log | grep _

Expands on exact token match regardless of where it appears.

Project-local abbreviations

Create a .abbrs file at your project root:

# .abbrs — repo-local shortcuts
regular k  kubectl
regular tf terraform
global  Y  | yq
  • The plugin walks up from $PWD and loads the first .abbrs it finds
  • Definitions switch automatically when you cd
  • Project-local wins over user abbreviations on name collision
  • This is a plain text file — track it in git, share it with your team

After editing by hand:

zabbr reload

Persistence

User abbreviations live in a dedicated file, never in .zshrc.

${ZSH_ABBR_USER_FILE:-${ZDOTDIR:-$HOME}/.zsh-abbr}

The plugin owns this file and rewrites it atomically, so comments are not preserved across writes.

Configuration

VariableDefaultDescription
ZSH_ABBR_USER_FILE${ZDOTDIR:-$HOME}/.zsh-abbrUser abbreviation file path
ZSH_ABBR_PROJECT_FILE_NAME.abbrsFile name for project-local abbreviations

Expansion rules

  • Expands on space, Enter, and the zabbr-expand widget
  • regular: command position only
  • global: exact token match at any position
  • Quoted tokens, backslash escapes, and $var are never expanded
  • Partial matches are never expanded
  • Tokens inside zabbr subcommands are never expanded

Installation

Manual

# in .zshrc
source /path/to/zsh-abbr-plugin/abbr.plugin.zsh

zinit

zinit light yachtida/zsh-abbr-plugin

zplug

zplug "yachtida/zsh-abbr-plugin"

oh-my-zsh (as plugin)

git clone https://github.com/yachtida/zsh-abbr-plugin \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-abbr-plugin

Then add zsh-abbr-plugin to plugins=() in .zshrc.

Development

# Run tests
zsh test/run.zsh

# Syntax check
zsh -n abbr.plugin.zsh lib/abbr-core.zsh lib/abbr-zle.zsh test/run.zsh

License

MIT © yachtida


日本語ドキュメント

はじめに

# プラグインを読み込む
source /path/to/zsh-abbr-plugin/abbr.plugin.zsh

# abbreviation を追加
zabbr add gc  'git commit'
zabbr add gp  'git push'
zabbr add -g G '| grep'

# 入力するだけで展開
gc  ──▶ git commit
gp G ──▶ git push | grep

space と Enter で自動展開されます。 手動展開キーを割り当てる場合:

bindkey '^X ' zabbr-expand   # Ctrl-X Space

機能

2 種類のスコープregular（command position のみ）と global（任意の位置）
プロジェクトローカルリポジトリに .abbrs を置くと cd に追従して自動切替
永続化ユーザー abbreviation は ~/.zsh-abbr に保存、.zshrc は書き換えない
ゼロ設定source するだけですぐ使える
安全クォート・エスケープ・$var は展開しない

コマンド

zabbr add [-g|--global] NAME EXPANSION   abbreviation を追加
zabbr list                               一覧表示
zabbr unset NAME                         削除
zabbr reload                             ユーザー + プロジェクトファイルを再読込
zabbr help [COMMAND]                     ヘルプを表示

引数なしの zabbr は zabbr list と同じです。

スコープ

regular — command position のみ

zabbr add gc 'git commit'

❯ gc<space>        ──▶  ❯ git commit _

simple command の先頭語でのみ展開されます （代入文・precommand modifier・リダイレクトの後を含む）。

global — 任意の位置

zabbr add -g G '| grep'

❯ cat log G<space> ──▶  ❯ cat log | grep _

位置を問わず、token が完全一致したときだけ展開されます。

プロジェクトローカル abbreviation

プロジェクトルートに .abbrs ファイルを置きます:

# .abbrs — リポジトリ専用ショートカット
regular k  kubectl
regular tf terraform
global  Y  | yq
  • カレントディレクトリから 親方向 に .abbrs を探索し、最初に見つかったものを読み込みます
  • cd すると定義が自動で切り替わります
  • 同名の場合、プロジェクトローカルがユーザー定義より優先されます
  • プレーンテキストなので、git で管理してチームと共有できます

手編集後は再読込:

zabbr reload

永続化

ユーザー abbreviation は専用ファイルに保存され、.zshrc は書き換えません。

${ZSH_ABBR_USER_FILE:-${ZDOTDIR:-$HOME}/.zsh-abbr}

プラグインがこのファイルを所有し、atomic に再生成するため、 コメントは書き込み時に保持されません。

環境変数

変数デフォルト説明
ZSH_ABBR_USER_FILE${ZDOTDIR:-$HOME}/.zsh-abbrユーザー abbreviation ファイルのパス
ZSH_ABBR_PROJECT_FILE_NAME.abbrsプロジェクトローカル abbreviation のファイル名

展開規則

  • space, Enter, zabbr-expand ウィジェットで展開
  • regular: command position のみ
  • global: 位置を問わず完全一致時のみ展開
  • クォート・バックスラッシュエスケープ・$var は展開しない
  • 部分一致は展開しない
  • zabbr サブコマンド内の token は展開しない

インストール

手動

# .zshrc に記述
source /path/to/zsh-abbr-plugin/abbr.plugin.zsh

zinit

zinit light yachtida/zsh-abbr-plugin

zplug

zplug "yachtida/zsh-abbr-plugin"

oh-my-zsh（プラグインとして）

git clone https://github.com/yachtida/zsh-abbr-plugin \
  ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-abbr-plugin

.zshrc の plugins=() に zsh-abbr-plugin を追加してください。

開発

# テスト実行
zsh test/run.zsh

# シンタックスチェック
zsh -n abbr.plugin.zsh lib/abbr-core.zsh lib/abbr-zle.zsh test/run.zsh

ライセンス

MIT © yachtida