zsh-abbr

zsh abbreviations — an enhanced zsh port of fish shell's abbr's auto-expanding abbreviations.

abbr manages abbreviations - user-defined words that are replaced with longer phrases after they are entered.

For example, a frequently-run command like git checkout can be abbreviated to gco. After entering gco and pressing Space, the full text git checkout will appear in the command line. To prevent expansion, press CtrlSpace in place of Space. Pressing Enter after an abbreviation will expand the abbreviation and accept the current line.

Abbreviations are expanded whether or not they are the first word on the line, like zsh's global aliases. Cross-session abbreviations are stored in the clear in a plaintext configuration file.

Run abbr --help (or abbr -h) for documentation.

Installation
Quick Start
Usage
Configuration
Changelog
Roadmap
Contributing
Uninstalling

Installation

Package

zsh-abbr is available on Homebrew. Run

brew install olets/tap/zsh-abbr

and follow the post-install instructions logged to the terminal.

Plugin

Or install zsh-abbr with your favorite plugin manager:

antibody: Add olets/zsh-abbr to your plugins file. If you use static loading, reload plugins.
Antigen: Add antigen bundle olets/zsh-abbr to your .zshrc.

Oh-My-Zsh:

Clone to OMZ's plugins' directory:

git clone https://github.com/olets/zsh-abbr.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-abbr

Add to the OMZ plugins array in your .zshrc:

plugins=( [plugins...] zsh-syntax-highlighting)

zgen: add zgen load olets/zsh-abbr to your .zshrc.

zinit (formerly zplugin): add this to your .zshrc:

zinit ice wait lucid
zinit light olets/zsh-abbr # or `load` instead of `light` to enable zinit reporting

zplug: add zplug "olets/zsh-abbr" to your .zshrc.

If running abbr gives an error "zsh: permission denied: abbr", reload zsh:

% source ~/.zshrc # or your custom .zshrc path

Manual

Clone this repo and add source path/to/zsh-abbr.zsh to your .zshrc.

Quick Start

# Add and use an abbreviation
% abbr m master
% m[Space] # expands to `master`
% git checkout m[Space] # becomes `git checkout master`
% git checkout m[Enter]
# expands to and runs `git checkout master`

% abbr gcm git checkout master
# Note the `m`s in `gcm` and `master` did not expand. Expansion only run on entire words
% gcm[Enter]
# expands to and runs `git checkout master`

# The above will in other open sessions, and in future sessions.
# Add an abbreviation only available in the current terminal
% abbr -g gco[Ctrl-Space] https://en.wikipedia.org/wiki/GCO
# (Note that Ctrl-Space opts out of space-triggered expansion)
% gco[Space] # expands to `https://en.wikipedia.org/wiki/GCO`

# Rename it
% abbr -r gco[Ctrl-Space] wgco
% gco[Space] # expands to `git checkout`
% wgco[Space] # expands to `https://en.wikipedia.org/wiki/GCO`

# Delete it
% abbr -g wgco[Ctrl-Space]
% wgco[Space] # no expansion

# Migrate your aliases to abbreviations
% abbr -p # creates abbreviations from all aliases
% abbr -i # creates abbreviations from all Git aliases, adding 'g' prefix

Usage

abbr <SCOPE> <OPTION> <ANY OPTION ARGUMENTS>

abbr <OPTION> <SCOPE> <ANY OPTION ARGUMENTS>

Scope

[(--global | -g) | (--universal | -U)]

A given abbreviation can be made available in the current zsh session (i.e. in the current terminal) —these are called global abbreviations— or to all terminals —these are called universal abbreviations.

Newly added universal abbreviations are available to all open sessions immediately.

Default is universal.

Options

abbr [(--add | -a)
      | (--clear-globals | -c)
      | (--erase | -e)
      | (--expand | -x)
      | (--git-populate | -i)
      | (--global | -g)
      | (--help | -h)
      | (--list | -l)
      | (--output-aliases | -o)
      | (--populate | -p)
      | (--rename | -r)
      | (--show | -s)
     ]

zsh-abbr has options to add, rename, and erase abbreviations; to add abbreviations for every alias or Git alias; to list the available abbreviations with or without their expansions; and to create aliases from abbreviations.

abbr with no arguments is shorthand for abbr --show. abbr ... with arguments and no flags is shorthand for abbr --add ....

Add

abbr [(--add | -a)] ABBREVIATION EXPANSION

Add a new abbreviation. To add a global abbreviation, use --global. Otherwise, or if the --universal scope is used, the new abbreviation will be universal.

% abbr --add gcm git checkout master
% gcm[Space] # expands as git checkout master
% gcm[Enter] # expands and accepts git checkout master

The following are equivalent:

% abbr --add --universal gcm git checkout master
% abbr -a --universal gcm git checkout master
% abbr --universal gcm git checkout master
% abbr --add -U gcm git checkout master
% abbr -a -U gcm git checkout master
% abbr -U gcm git checkout master
% abbr gcm git checkout master

A -- may optionally follow the last option.

The following are not allowed in the abbreviation: ;, |, &&, and whitespace.

abbr a\;b c # will error
abbr 'a||b' c # will error

Abbreviations can also be manually added to the ZSH_ABBR_UNIVERSALS_FILE.

Clear Globals

abbr (--clear-globals | -c)

Erase all global abbreviations.

Erase

abbr (--erase | -e) ABBREVIATION

Erase an abbreviation. Specify --global scope to erase a global abbreviation. Otherwise, or if the --universal scope is used, a universal abbreviation will be erased.

% abbr --add gcm git commit master
% gcm[Enter] # expands and accepts git commit master
Switched to branch 'master'
% abbr --erase gcm[Ctrl-Space][Enter]
% gcm[Space|Enter] # nothing
% abbr --add --global gcm echo gimme cookie monster
% gcm[Enter]
gimme cookie monster
% abbr --erase --global gcm[Ctrl-Space][Enter]
% gcm[Enter]
Already on 'master'

Universal abbreviations can also be manually erased from the ZSH_ABBR_UNIVERSALS_FILE.

Expand

abbr (--expand | -x) ABBREVIATION

Output the ABBREVIATION's EXPANSION. Useful in scripting.

% abbr --add gc git checkout
% abbr --expand gc[Ctrl-Space]
git checkout

Git Populate

abbr (--git-populate | -i)

Add abbreviations for every Git alias available in the current session. WORDs are prefixed with g; EXPANSIONs are prefixed with git[Space]. Use the --global scope to create global abbreviations. Otherwise, or if the --universal scope is used, the Git abbreviations will be universal.

This command is useful for migrating from aliases to abbreviations.

% git config alias.co checkout
% abbr --git-populate --global
% gco[Space] # expands to git checkout
% source ~/.zshrc
% gco[Space] # no expansion
% abbr --git-populate
% source ~/.zshrc
% gco[Space] # expands to git checkout

Note for users migrating from Oh-My-Zsh: OMZ's Git aliases are shell aliases, not aliases in the Git config. To add abbreviations for them, use Populate.

List

abbr (--list|-l)

List all abbreviations available in the current shell. Universal abbreviations appear first.

% abbr a apple
% abbr b ball
% abbr -g c cat
% abbr -l
a
b
c
% source ~/.zshrc
% abbr -l
a
b

Output Aliases

abbr (--output-aliases | -o) [DESTINATION]

Export abbreviations as aliases declarations. To export global abbreviations, use --global. Otherwise, or if the --universal scope is used, universal abbreviations are exported.

% abbr --add gcm git checkout master
% abbr --add --global g git

% abbr --output-aliases
alias -g gcm='git checkout master'

% abbr --output-aliases --global
alias -g g='git'

% abbr --output-aliases ~/.zshrc
% cat ~/.zshrc
# -- snip --
alias -g g='git'

Populate

abbr (--git-populate | -i)

Add abbreviations for every alias available in the current session. Use the --global scope to create global abbreviations. Otherwise, or if the --universal scope is used, the abbreviations will be universal.

This command is useful for migrating from aliases to abbreviations.

Rename

abbr (--rename | -r) OLD_WORD NEW_WORD

Rename an abbreviation. Use the --global scope to rename a global abbreviation. Otherwise, or if the --universal scope is used, a universal abbreviation will be renamed.

% abbr --add gcm git checkout master
% gcm[Space] # expands to git checkout master
% gm[Space] # no expansion
% abbr --rename gcm[Ctrl-Space] gm
% gcm[Space] # no expansion
% gm[Space] # expands to git checkout master

Abbreviations can also be manually renamed in the ZSH_ABBR_UNIVERSALS_FILE.

Show

abbr [(--show|-s)]

Show all the abbreviations available in the current session, along with their expansions. Show does not take a scope. Global abbreviations are marked -g and follow universal abbreviations, which are marked -U.

% abbr --add gcm git checkout master
% abbr --add --global a apple
% abbr --show # or `abbr` with no arguments
abbr -a -U -- gcm git checkout master
abbr -a -g -- a apple
% source ~/.zshrc
% abbr --show
abbr -a -U -- gcm git checkout master

Configuration

Storage

Universal abbreviations live in a plain text file which you can manually edit, shared, etc. Its default location is ${HOME}/.config/zsh/universal-abbreviations. Customize this by setting the ZSH_ABBR_UNIVERSALS_FILE variable in your .zshrc before loading zsh-abbr.

% cat ~/.zshrc
# -- snip --
ZSH_ABBR_UNIVERSALS_FILE="path/to/my/universal/abbreviations"
# -- snip --
# load zsh-abbr

The default file is created the first time zsh-abbr is run. If you customize the path, you may want to delete the default file or even the default zsh-abbr config directory.

Note: order in the file will not necessarily be preserved, as zsh does not order associative arrays.

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.)

If you want to set your own bindings, set ZSH_ABBR_DEFAULT_BINDINGS to false in your .zshrc before loading zsh-abbr. In the following example, expansion is bound to Ctrla:

% cat ~/.zshrc
# -- snip --
ZSH_ABBR_DEFAULT_BINDINGS=false
bindkey "^A" _zsh_abbr_expand_space
# -- snip --
# load zsh-abbr

Uninstalling

Delete the zsh-abbr configuration directory. Note that this will permanently delete the universal abbreviations file.

% rm -rf $(dirname "$ZSH_ABBR_UNIVERSALS_FILE")

Then follow the standard uninstallation procedure for your installation method. This is typically the reverse of what you did to install.

Changelog

See the CHANGELOG file.

Roadmap

See the ROADMAP file.

Contributing

Thanks for your interest. Contributions are welcome!

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Check the Issues to see if your topic has been discussed before or if it is being worked on. You may also want to check the roadmap (see above). Discussing in an Issue before opening a Pull Request means future contributors only have to search in one place.

This project loosely follows the Angular commit message conventions. This helps with searchability and with the changelog, which is generated automatically and touched up by hand only if necessary. Use the commit message format <type>(<scope>): <subject>, where <type> is feat for new or changed behavior, fix for fixes, docs for documentation, style for under the hood changes related to for example zshisms, refactor for other refactors, test for tests, or chore chore for general maintenance (this will be used primarily by maintainers not contributors, for example for version bumps). <scope> is more loosely defined. Look at the commit history for ideas.

License

This project is licensed under MIT license. For the full text of the license, see the LICENSE file.

philwhln / zsh-abbr