Appearance
Essential commands
DANGER
These docs are for the not-yet-released v6.
For v5 docs visit https://zsh-abbr.olets.dev
zsh-abbr has broad capabilities for managing abbreviations. Add, rename, erase, import, export. Customize the interactive behavior. Customize where data is stored. There's a lot you can learn. Here's what you need to know:
Create abbreviations
Add an abbreviation with abbr <ABBREVIATION>=<EXPANSION>
:
shell
% abbr hw="echo hello world"
Added the regular user abbreviation `hw`
%
By default, abbreviations are immediately available to all current and future sessions (that is, in all open and future terminals). You can also create session abbreviations which are available only in the session they are created in. Read Usage > Scope.
Expand them
Space expands abbreviations:
shell
% abbr hw="echo hello world"
Added the regular user abbreviation `hw`
% hw[Space] # expands to `echo hello world `
Enter expands and accepts abbreviations:
shell
% abbr hw="echo hello world"
Added the regular user abbreviation `hw`
% hw[Enter] # expands to `echo hello world` and runs the command
hello world
%
By default, abbreviations only expand at the start of the command line. These are called "regular" abbreviations. You can also create "global" abbreviations which expand everywhere. Read Usage > Type.
As demonstrated above, the EXPANSION can be more than one word. The ABBREVIATION can be too. This lets you create context-dependent abbreviations:
shell
% abbr "git cp"="git cherry-pick"
Added the regular user abbreviation `git cp`
% cp[Space] # no special behavior. you can use cp as usual
% git cp[Space] # expands to `git cherry-pick `
This lets you compose multi-stage abbreviations:
shell
% abbr g=git
Added the regular user abbreviation `g`
% g[Space] # expands to `git `
% abbr "git cp"="git cherry-pick"
Added the regular user abbreviation `git cp`
% cp[Space] # no special behavior. you can use cp as usual
% g[Space]cp[Space] # expands to `git cherry-pick `
TIP
If the above example excites you, check out zsh-abbr's git command. It streamlines the process of creating Git-related abbreviations!
Place the cursor
You can tell zsh-abbr to move the cursor to somewhere in the expansion after expanding. Toggle on ABBR_SET_EXPANSION_CURSOR
:
shell
# .zshrc
ABBR_SET_EXPANSION_CURSOR=1
and then use ABBR_EXPANSION_CURSOR_MARKER
in your abbreviations:
shell
% abbr git m="commit -m \"%\""
Added the regular user abbreviation `m`
Added the global user abbreviation `git m`
% m[SPACE] # expands to `git commit -m "[CURSOR]"`
You can use this to disable the default key binding's trailing space:
shell
% abbr hasspace=yes
% abbr nospace=no%
% hasspace[SPACE]nospace[SPACE]ne # `yes none`
You can even move the cursor when not expanding, to build command "templates". Toggle on ABBR_SET_LINE_CURSOR
:
shell
# .zshrc
ABBR_SET_LINE_CURSOR=1
and then use ABBR_LINE_CURSOR_MARKER
in your abbreviations:
shell
% ABBR_SET_EXPANSION_CURSOR=1
% ABBR_SET_LINE_CURSOR=1
% abbr template="a%b % c%d"
% template[SPACE] # expands to `a[CURSOR]b % c%d`, thanks to ABBR_SET_EXPANSION_CURSOR
% a[type xSPACE]b % c%d # cursor moves: `ax b [CURSOR] c %`, thanks to ABBR_SET_LINE_CURSOR
% ax b [type ySPACE] c%d # cursor moves: `ax b y c [CURSOR]`, thanks to ABBR_SET_LINE_CURSOR
% ax b y c [CURSOR]
Known limitation
ABBR_EXPANSION_CURSOR_MARKER
cannot be ^
. Read issue #140 for details.
TIP
Learn how to customize cursor markers in Configuration Variables
Ditch aliases
Find you prefer abbreviations to aliases? zsh-abbr makes it easy to create abbreviations from your aliases. The aliases are left untouched, so you can still use them when you want to… or delete them!
zsh-abbr has support for importing both zsh aliases and Git aliases. Learn more at: