Repository files navigation

Simple zsh plugin that reminds you that you should use one of yourexisting aliases for a command you just typed.

Also supports detection of global and git aliases.

• Usage
• Requirements
• Installation

Customization

• Message Position
• Displaying Results
• Customising Messages

Advanced Features

• Hardcore Mode
• Hardcore Mode for specific Aliases
• Check your Alias usage
• Disable Hints for specific Aliases
• Temporarily Disabling Messages

Contributing

• Contributing
• Running Tests

You can also view theCHANGELOG for a history of changes.

You dont need to do anything. Once it's installed,zsh-you-should-use will let you know if you wrote a command with anexisting alias.

you-should-use also detects global aliases:

and Git aliases:

you-should-use officially supports zsh versions 5.1 onwards.

It is possible the plugin might work on even older versions.However they would not have been tested as part of the CI test process.

Add one of the following to your.zshrc file depending on yourpackage manager:

ZPlug

zplug "MichaelAquilina/zsh-you-should-use"

Antigen

antigen bundle "MichaelAquilina/zsh-you-should-use"

Zgen

zgen load "MichaelAquilina/zsh-you-should-use"

oh-my-zsh

Clone this repository using the following command:

git clone https://github.com/MichaelAquilina/zsh-you-should-use.git${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/you-should-use

$ZSH_CUSTOM is oh-my-zsh’s customization directory (docs).

Then addyou-should-use to theplugins array in your.zshrc:

plugins=(# ...    you-should-use# ...)

Arch Linux

Install thezsh-you-should-use (AUR) package:

yay -S zsh-you-should-use

Then add this line to your.zshrc:

source /usr/share/zsh/plugins/zsh-you-should-use/you-should-use.plugin.zsh

By default,you-should-use will display its reminder messagebeforea command has executed. However, you can choose to display the mesasgeafter acommand has executed by setting the value ofYSU_MESSAGE_POSITION.

export YSU_MESSAGE_POSITION="after"

By default,you-should-use will display the best match from anymatching aliases found. However, you can change this behaviour so thatit displaysall matches found by setting the value ofYSU_MODE.

• To only display best match (default):export YSU_MODE=BESTMATCH
• To display all matches:export YSU_MODE=ALL

By default, the following message is displayed in bold when an alias is found:

Found existing %alias_type for "%command". You should use: "%alias"

Where the following variables represent:

• %alias_type - the type of alias detected (alias, git alias, global alias)
• %command - the command that was typed by the user
• %alias - the matching alias that was found

This default message can be customised by setting theYSU_MESSAGE_FORMAT environment variable.

If for example, you wish to display your own custom message in red, you can add thefollowing to your~/.zshrc:

export YSU_MESSAGE_FORMAT="$(tput setaf 1)Hey! I found this %alias_type for %command: %alias$(tput sgr0)"

$(tput setaf 1) generates the escape code terminals use for red foreground text.$(tput sgr0) setsthe text back to a normal color.

You can read more about how you can use tput and terminal escape codes here:http://wiki.bash-hackers.org/scripting/terminalcodes

For the brave and adventerous only

You can enable Hardcore mode to enforce the use of aliases. Enablingthis will cause zsh to refuse to execute commands you have entered if analternative alias for it exists. This is a handy way of forcing you touse your aliases and help you turn those aliases into muscle memory.

Enable hardcore mode by setting the variableYSU_HARDCORE to 1.

export YSU_HARDCORE=1

Now if you type a command that has an alias defined and you didnt useit, zsh will refuse to execute that command:

$ export YSU_HARDCORE=1$ ls -lhFound existing alias for "ls -lh". You should use: "ll"You Should Use hardcore mode enabled. Use your aliases!$ lltotal 8.0K-rw-r--r-- 1 michael users 2.4K Jun 19 20:46 README.md-rw-r--r-- 1 michael users  650 Jun 19 20:42 you-should-use.plugin.zsh

If you want hardcore mode behavior but only for specific aliases, you can useYSU_HARDCORE_ALIASES.This allows you to selectively enforce specific aliases without enabling full hardcore mode.

SetYSU_HARDCORE_ALIASES to an array of alias names that should trigger hardcore behavior:

export YSU_HARDCORE_ALIASES=("gs" "ll" "gco")

Now when you type a command that matches one of these specific aliases, zsh will refuse to execute it:

$ export YSU_HARDCORE_ALIASES=("gs" "ll")$ git statusFound existing alias for "git status". You should use: "gs"You Should Use hardcore mode enabled. Use your aliases!$ ls -lhFound existing alias for "ls -lh". You should use: "ll"You Should Use hardcore mode enabled. Use your aliases!$ git checkout mainFound existing alias for "git checkout". You should use: "gco"# This command executes normally since "gco" is not in YSU_HARDCORE_ALIASES

NOTE:YSU_HARDCORE_ALIASES only works whenYSU_HARDCORE is not set. IfYSU_HARDCORE isenabled, it takes precedence and will enforce all aliases.

IMPORTANT: Aliases listed inYSU_IGNORED_ALIASES (Disable Hints for specific Aliases) willtake precedence overYSU_HARDCORE_ALIASES. If an alias is in both lists, it will be ignored andwon't trigger hardcore mode.

It's often useful to check how often we use our aliases so that we have an idea of which ones wecould probably get rid of (or remind ourselves of them if we forgot).zsh-you-should-use providesa convenience functioncheck_alias_usage which you can run to analyse your alias usage.

$ check_alias_usage924: curl='curl --silent'652: gco='git checkout'199: json='jq '.' -C'157: less='less -R'100: ll='ls -lh --group-directories-first'93: vim='nvim'76: watch='watch '61: v='vim'60: md='mkdir'39: gr='git rebase'38: dc='docker-compose'35: ls='ls --color=auto'33: h='history'28: dcr='docker-compose

check_alias_usage analyses your history to generate this data for you. If your history is disabledor if you limit your history to a certain amount of time, then the alias report generated will be a reflectionof the limited data available.

Optionally, you can limit how farcheck_alias_usage looks back in history by providing an optional numericparameter. This parameter specifies how many entries in the history to check when generating the report.In the example below, history is limited to the last 200 entries when generating the alias report.

$ check_alias_usage 2009: h='history'3: gpoh='git push -u origin HEAD'3: gco='git checkout'2: v='vim'2: ll='ls -lh --group-directories-first'2: gpohw='gpoh && git web --pull-request'2: gc='git commit'2: gap='git add -p'2: ap='ansible-playbook'1: xopen='GDK_BACKEND=wayland xdg-open'1: t='tig'1: gw='git web'1: gs='git status'

You can tellyou-should-use to permanently ignore certain aliases by including them in theYSU_IGNORED_ALIASES variable (which is an array):

$ ls -lFound existing alias for "ls -l". You should use: "ll"$ export YSU_IGNORED_ALIASES=("g" "ll")$ ls -l

If you want to ignore global aliases, use theYSU_IGNORED_GLOBAL_ALIASES environment variable.

$ cd ../..Found existing global alias for "../..". You should use: "..."$ export YSU_IGNORED_GLOBAL_ALIASES=("...")$ cd ../..

You can temporarily disable you should use by running the commanddisable_you_should_use.

When you want to re-enable messages, run the commandenable_you_should_use.

Pull requests and Feedback are welcome! 🎉

I have tried to cater for as many use cases that I can think of.However, they are naturally tailored to to my own workflow and I couldbe missing many others.

Because of this if there is a specific use case that does not work asyou would expect or if you have any suggestions to how the plugin shouldbehave, feel free toopen anissue

Installzunit. Runzunit in the rootdirectory of the repo.

$ zunitLaunching ZUnitZUnit: 0.8.2ZSH:   zsh 5.3.1 (x86_64-suse-linux-gnu)✔ ysu message correct output✔ ysu global message correct output✔ ysu git message correct output

NOTE: It is required that you use a minimum zunit version of 0.8.2

NOTE: The tests that run move your git configuration to a temporarylocation during the test process so that your user configuration doesnot interfere with tests. This will be restored at the end of each testso there is no risk in losing your settings. If for some strange reasonzunit crashes or does not restore your git configuration automatically,all you need to do is runmv ~/.gitconfig.bak ~/.gitconfig