These are the v4 docs. For v5 docs see

Configuration variables

In addition to the following, setting NO_COLOR (regardless of its value) will disable color output. See

ABBR_AUTOLOADintegerIf non-zero, automatically account for updates to the user abbreviations file (see Storage and manual editing)1
ABBR_DEBUGintegerIf non-zero, print debugging messages0
ABBR_DEFAULT_BINDINGSintegerIf non-zero, add the default bindings (see Bindings)1
ABBR_DRY_RUNintegerIf non-zero, use dry run mode without passing --dry-run0
ABBR_FORCEintegerIf non-zero, use force mode without passing --force (see add)0
ABBR_PRECMD_LOGSintegerIf non-zero, support precmd logs, for example to warn that a deprecated widget was used1
ABBR_QUIETintegerIf non-zero, use quiet mode without passing --quiet0
ABBR_QUIETERintegerIf non-zero, use quieter mode without passing --quieter0
ABBR_TMPDIRStringPath to the directory temporary files are stored in. Ends in /${${TMPDIR:-/tmp}%/}/zsh-abbr/ *
ABBR_USER_ABBREVIATIONS_FILEStringPath to the file user abbreviation are stored in (see Storage and manual editing)$XDG_CONFIG_HOME/zsh/abbreviations if you have XDG_CONFIG_HOME defined**, otherwise $HOME/.config/zsh/abbreviations ***

* If changing this, you may want to delete the default directory.

** Unless you've been using zsh-abbr without a customized ABBR_USER_ABBREVIATIONS_FILE since before XDG_CONFIG_HOME support was added (v4.8.0). In that case zsh-abbr will use the pre-4.8.0 $HOME/.config/zsh/abbreviations.

*** If changing this, you may want to delete the default file.

Exported variables

In addition to exporting the configuration variables above, zsh-abbr creates the following variables:

ABBR_GLOBAL_SESSION_ABBREVIATIONSassociative arrayThe global session abbreviations
ABBR_GLOBAL_USER_ABBREVIATIONSassociative arrayThe global user abbreviations
ABBR_INITIALIZINGintegerSet to 1 when zsh-abbr is initializing
ABBR_LOADING_USER_ABBREVIATIONSintegerSet to 1 when the interactive shell is refreshing its list of user abbreviations, otherwise not set
ABBR_PRECMD_MESSAGEprompt stringMessage shown by precmd hook if ABBR_PRECMD_LOGS is non-zero
ABBR_REGULAR_SESSION_ABBREVIATIONSassociative arrayThe regular session abbreviations
ABBR_SOURCE_PATHstringPath to the zsh-abbr.zsh
ABBR_REGULAR_USER_ABBREVIATIONSassociative arrayThe regular user abbreviations

Each element in ABBR_GLOBAL_SESSION_ABBREVIATIONS, ABBR_GLOBAL_USER_ABBREVIATIONS, ABBR_REGULAR_SESSION_ABBREVIATIONS, and ABBR_REGULAR_USER_ABBREVIATIONS has the form ABBREVIATION=EXPANSION. The expansion value is quoted. Scripters will probably want to remove one level of quotes, using the Q modifier (e.g. for v in ${(Qv)ABBR_REGULAR_USER_ABBREVIATIONS}...).

Storage and manual editing

User abbreviations live in a plain text file which you can edit directly, share, keep in version control, etc. Abbreviations in this file are loaded when each new session is opened; non-abbr commands will be ignored and then excised from the file.

zsh-abbr automatically keeps the user abbreviations storage file alphabetized, with all global user abbreviations before the first regular user abbreviation.

Every time an abbr command is run, the session's updates its user abbreviations with the latest from the user abbreviations file. This should add no appreciable time, but you prefer it can be turned off by setting ABBR_AUTOLOAD=0.

To refresh the user abbreviations from the user abbreviation, run abbr load (or any other abbr command).


By default

  • Space expands abbreviations
  • CtrlSpace is a normal space
  • Enter expands and accepts abbreviations

(In incremental search mode, Space is a normal space and CtrlSpace expands abbreviations.)

There are three available widgets:

WidgetBehaviorDefault binding
abbr-expandIf following an abbreviation, expands it.
Replaces deprecated _abbr_expand_widget
Not bound
abbr-expand-and-acceptIf following an abbreviation, expands it; then accepts the line.
Replaces deprecated _abbr_expand_and_accept
abbr-expand-and-spaceIf following an abbreviation, expands it; then adds a space.
Replaces deprecated _abbr_expand_and_space

In the following example, additional bindings are added such that Ctrle expands abbreviations without adding a trailing space and Ctrla has the same behavior as Space.

% cat ~/.zshrc
# -- snip --
bindkey "^E" abbr-expand
bindkey "^A" abbr-expand-and-space
# -- snip --

To prevent the creation of the default bindings, set ABBR_DEFAULT_BINDINGS to 0 before initializing zsh-abbr. In the following example, CtrlSpace expands abbreviations and Space is not bound to any zsh-abbr widget.

% cat ~/.zshrc
# -- snip --
bindkey "^ " abbr-expand-and-space
# -- snip --
# load zsh-abbr
# -- snip --


fast-syntax-highlighting users see #24.

To highlight user abbreviations that will expand, zsh-syntax-highlighting users can add these lines to .zshrc below where zsh-abbr is loaded. For more info see the zsh-syntax-highlighting regexp highlighter documentation.

Replace <styles for global abbreviations> with a zsh character highlighting string (start at "The available types of highlighting are the following."). For example fg=blue, fg=blue,bg=red,bold, etc.


ZSH_HIGHLIGHT_REGEXP+=('^[[:blank:][:space:]]*('${(j:|:)${(k)ABBR_REGULAR_USER_ABBREVIATIONS}}')$' <styles for regular abbreviations>)
ZSH_HIGHLIGHT_REGEXP+=('\<('${(j:|:)${(k)ABBR_GLOBAL_USER_ABBREVIATIONS}}')$' <styles for global abbreviations>)


ZSH_HIGHLIGHT_REGEXP=('^[[:blank:][:space:]]*('${(j:|:)${(k)ABBR_REGULAR_USER_ABBREVIATIONS}}')$' <styles for regular abbreviations>)
ZSH_HIGHLIGHT_REGEXP+=('[[:<:]]('${(j:|:)${(k)ABBR_GLOBAL_USER_ABBREVIATIONS}}')$' <styles for global abbreviations>)

vi mode compatibility

Switching to vi mode —with plain old bindkey -v or with plugin vi/Vim mode plugin that calls bindkey -v — will wipe out the keybindings zsh-abbr's interactive behavior relies on. If you use vi mode, enable it before initializing zsh-abbr. For example, the simplest .zshrc for a zinit user would be

bindkey -v
zinit light olets/zsh-abbr

macOS System Text Substitutions

The following snippet will make your global macOS text substitutions available in the shell.

for substitution in ${(f)"$(defaults read ~/Library/Preferences/.GlobalPreferences.plist NSUserDictionaryReplacementItems | plutil -convert json -o - - | jq -r 'to_entries[] | "\(.value.replace)=\(.value.with)"')"}; do
  abbr add [options] "$substitution"