Advanced
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_EXPANSION_CURSOR_MARKER | string | See ABBR_SET_EXPANSION_CURSOR | $ABBR_LINE_CURSOR_MARKER |
ABBR_FORCE | integer | If non-zero, use force mode without passing --force (see Usage > Commands > add) | 0 |
ABBR_LINE_CURSOR_MARKER | string | See ABBR_SET_LINE_CURSOR | % |
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 (see 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 (see also Widgets and key bindings) | 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_PRECMD_MESSAGE | prompt string | ⚠️ DEPRECATED ⚠️ 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}...).
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. 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 limitation: the following fast-syntax-highlighting solution only supports single-word abbreviations. 🌟 Want highlighting for multi-word abbreviations? See zsh-abbr#24.
# 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 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:
# load zsh-abbr, then
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
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