Advanced

• Configuration variables
• Exported variables
• Storage and manual editing
• Widgets and key bindings
• Integrations
  • Syntax highlighting
    • fast-syntax-highlighting
    • zsh-syntax-highlighting
  • vi mode
  • macOS System Text Substitutions

Configuration variables

Variable	Type	Use	Default
ABBR_AUTOLOAD	integer	If non-zero, automatically account for updates to the user abbreviations file (see Storage and manual editing)	1
ABBR_DEBUG	integer	If non-zero, print debugging messages	0
ABBR_DEFAULT_BINDINGS	integer	If non-zero, add the default bindings (see Widgets and key bindings)	1
ABBR_DRY_RUN	integer	If non-zero, use dry run mode without passing --dry-run	0
ABBR_FORCE	integer	If non-zero, use force mode without passing --force (see Usage > Commands > add)	0
ABBR_PRECMD_LOGS	integer	If non-zero, support precmd logs, for example to warn that a deprecated widget was used	1
ABBR_QUIET	integer	If non-zero, use quiet mode without passing --quiet	0
ABBR_QUIETER	integer	If non-zero, use quieter mode without passing --quieter	0
ABBR_TMPDIR	String	Path to the directory temporary files are stored in. Ends in /	${${TMPDIR:-/tmp}%/}/zsh-abbr/ If changing this, you may want to delete the default directory.
ABBR_USER_ABBREVIATIONS_FILE	String	Path to the file user abbreviation are stored in (see Storage and manual editing)	${XDG_CONFIG_HOME:-$HOME/.config}/zsh-abbr/user-abbreviations with legacy support for using ${XDG_CONFIG_HOME:-$HOME/.config}/zsh/abbreviations instead if a file exists at that path If changing this, you may want to delete the default file.
NO_COLOR	mixed	If set (to any value or no value at all) abbr will not use color in its output. See https://no-color.org/.

Exported variables

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

Variable	Type	Value
ABBR_GLOBAL_SESSION_ABBREVIATIONS	associative array	The global session abbreviations
ABBR_GLOBAL_USER_ABBREVIATIONS	associative array	The global user abbreviations
ABBR_INITIALIZING	integer	Set to 1 when zsh-abbr is initializing
ABBR_LOADING_USER_ABBREVIATIONS	integer	Set to 1 when the interactive shell is refreshing its list of user abbreviations, otherwise not set
ABBR_PRECMD_MESSAGE	prompt string	Message shown by precmd hook if ABBR_PRECMD_LOGS is non-zero
ABBR_REGULAR_SESSION_ABBREVIATIONS	associative array	The regular session abbreviations
ABBR_SOURCE_PATH	string	Path to the zsh-abbr.zsh
ABBR_REGULAR_USER_ABBREVIATIONS	associative array	The 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).

Widgets and key bindings

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:

Widget	Behavior	Default binding
abbr-expand	If following an abbreviation, expands it	Not bound
abbr-expand-and-accept	If following an abbreviation, expands it; then accepts the line	Enter
abbr-expand-and-space	If following an abbreviation, expands it; then adds a space	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 --
ABBR_DEFAULT_BINDINGS=0
bindkey "^ " abbr-expand-and-space
# -- snip --
# load zsh-abbr
# -- snip --

Integrations

WARNING

These integrations are not regularly tested. It is possible that they are out of date. Pull requests are welcome to fix broken integrations. The zsh-abbr maintainer does not commit to keeping them working — if something breaks and the maintainer and the community does not have a fix, it may be removed from this documentation.

Syntax highlighting

fast-syntax-highlighting

To highlight user abbreviations that will expand, fast-syntax-highlighting users can add these lines to .zshrc below where zsh-abbr and all abbreviations are loaded.

Known limitation: the following zsh-syntax-highlighting solution only supports single-word abbreviations. 🌟 Want highlighting for multi-word abbreviations? See zsh-abbr#24.

chroma_single_word() {
  (( next_word = 2 | 8192 ))

  local __first_call="$1" __wrd="$2" __start_pos="$3" __end_pos="$4"
  local __style

  (( __first_call )) && { __style=${FAST_THEME_NAME}alias }
  [[ -n "$__style" ]] && (( __start=__start_pos-${#PREBUFFER}, __end=__end_pos-${#PREBUFFER}, __start >= 0 )) && reply+=("$__start $__end ${FAST_HIGHLIGHT_STYLES[$__style]}")

  (( this_word = next_word ))
  _start_pos=$_end_pos

  return 0
}

register_single_word_chroma() {
  local word=$1
  if [[ -x $(command -v $word) ]] || [[ -n $FAST_HIGHLIGHT["chroma-$word"] ]]; then
    return 1
  fi

  FAST_HIGHLIGHT+=( "chroma-$word" chroma_single_word )
  return 0
}

if [[ -n $FAST_HIGHLIGHT ]]; then
  for abbr in ${(f)"$(abbr list-abbreviations)"}; do
    if [[ $abbr != *' '* ]]; then
      register_single_word_chroma ${(Q)abbr}
    fi
  done
fi

zsh-syntax-highlighting

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.

Known limitation: the following zsh-syntax-highlighting solutions do not support unmatched parentheses within abbreviations. For example the valid abbr '('='(x' will make zsh-syntax-highlighting error. 🌟 Have a better solution? Please contribute it!

Linux:

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

macOS:

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

After adding the snippets, all new terminals will use them. To use them in an already-open terminal, restart zsh in that terminal:

exec zsh

vi mode

Switching to vi mode —with plain old bindkey -v or with a 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.

# .zshrc

bindkey -v
# load zsh-abbr here

macOS System Text Substitutions

Add the following snippet to your .zshrc file to create abbreviation for all macOS text substitutions.

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"
done