Advanced

Heads Up

v6 is out. See the v5.x -> v6.x migration guide

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

Configuration variables

Variable	Type	Use	Default	Limitations
ABBR_AUTOLOAD	integer	If non-zero, automatically account for updates to the user abbreviations file (read 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 (read Widgets and key bindings)	1
ABBR_DRY_RUN	integer	If non-zero, use dry run mode without passing --dry-run	0
ABBR_EXPANSION_CURSOR_MARKER	string	Read ABBR_SET_EXPANSION_CURSOR in this table	$ABBR_LINE_CURSOR_MARKER	Cannot contain ^. Read issue #140.
ABBR_FORCE	integer	If non-zero, use force mode without passing --force (read Usage > Commands > add)	0
ABBR_LINE_CURSOR_MARKER	string	Read ABBR_SET_LINE_CURSOR in this table	%
ABBR_PRECMD_LOGS	integer	⚠️ DEPRECATED ⚠️ 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_SET_EXPANSION_CURSOR	integer	If non-zero and the expansion includes ABBR_EXPANSION_CURSOR_MARKER, abbr-expand will replace the expansion's first instance of ABBR_EXPANSION_CURSOR_MARKER with the cursor, and abbr-expand-and-insert's bound key will not be inserted at the end of the expansion (read also Widgets and key bindings)	0
ABBR_SET_LINE_CURSOR	integer	If non-zero and abbr-expand didn't place the cursor (because the ABBR_SET_EXPANSION_CURSOR is zero or the expansion did not include ABBR_EXPANSION_CURSOR_MARKER), abbr-expand-and-insert will replace the line's first instance of ABBR_LINE_CURSOR_MARKER with the cursor instead of inserting its bound key at the end of the expansion (read also Widgets and key bindings)	0
ABBR_TMPDIR	String	Path to the directory temporary files are stored in.	${${TMPDIR:-/tmp}%/}/zsh-abbr/ for users without privileges, ${${TMPDIR:-/tmp}%/}/zsh-abbr/ for users with privileges (e.g. su) If changing this, you may want to delete the default directory. As of v5.7.0, custom values for this variable do not have to end in /.
ABBR_USER_ABBREVIATIONS_FILE	String	Path to the file user abbreviation are stored in (read 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. Learn more at 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_PRECMD_MESSAGE	prompt string	⚠️ DEPRECATED ⚠️ Message printed 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}...).

Transient exported variables

zsh-abbr exports the following variables in limited contexts:

Variable	Type	Value
ABBR_INITIALIZING	integer	Set to 1 when zsh-abbr is initializing, otherwise not set
ABBR_LOADING_USER_ABBREVIATIONS	integer	Set to 1 when the interactive shell is refreshing its list of user abbreviations, otherwise not set

Storage and manual editing

User abbreviations live in a plain text file which you can edit directly, share, keep in version control, etc.

The path to the file is stored in the ABBR_USER_ABBREVIATIONS_FILE configuration variable. Read Configuration variables for details.

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-insert	If following an abbreviation, expands it; then adds a space	Space ("^ "); in search mode, Ctrl Space (-M isearch "^ ")
abbr-expand-and-space	⚠️ DEPRECATED ⚠️ Alias for abbr-expand-and-insert	Not bound

zsh-abbr also binds Ctrl Space ("^ ") to magic-space and, in search mode, Space (-M isearch " ") to magic-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-insert
# -- 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-insert
# -- snip --
# load zsh-abbr
# -- snip --

Alternative keymaps

By default, zsh-abbr is only enabled for the default keymap. To enable a widget for another keymap, run bindkey -M. For example, the following extends zsh-abbr's default behavior to the viins keymap:

bindkey -M viins " " abbr-expand-and-insert
bindkey -M viins "^ " magic-space
bindkey -M viins "^M" abbr-expand-and-accept

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 limitations:

1. the following fast-syntax-highlighting solution only supports single-word abbreviations. 🌟 Want highlighting for multi-word abbreviations? Read zsh-abbr#24.
2. Only and all of the abbreviations defined when the shell was started will be highlighted. fast-syntax-highlighting won't know about any abbreviation additions, erasures, or renames. To update fast-syntax-highlighting, open a new terminal, or restart the shell by running exec zsh.

# load zsh-abbr, then

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 read the zsh-syntax-highlighting regexp highlighter documentation.

Replace <styles for …> 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 limitations:

1. 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!
2. Only and all of the abbreviations defined when the shell was started will be highlighted. zsh-syntax-highlighting won't know about any abbreviation additions, erasures, or renames. To update zsh-syntax-highlighting, open a new terminal, or restart the shell by running exec zsh.

Linux:

# load zsh-abbr, then

# make sure to replace `<styles for …>` (read above)

(( ${#ABBR_REGULAR_USER_ABBREVIATIONS} )) && {
  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:

# load zsh-abbr, then

# make sure to replace `<styles for …>` (read above)

(( ${#ABBR_REGULAR_USER_ABBREVIATIONS} )) && {
  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 bindkey -v or software which 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

Suggestions

For zsh-autosuggestions integration, use zsh-autosuggestions-abbreviations-strategy.