My ZSH configuration

This repository has a fully loaded configuration for ZSH. The configuration make opinionated choices based on my own desires for what a shell should be like.

It's strongly advised that you write your own configuration instead of just using this one. That way you can understand what you are doing and maybe gain a better appreciation for the shell and its features.

The configuration is broken down into modules where possible, this makes it easier to hack on.

Usage

Clone this repository to ~/.config/zsh

Inside of that directory run:

git submodule init
git submodule update

This will pull my plug-in manager ZshPlug.

And then add the following into ~/.zshenv:

export ZDOTDIR="${XDG_CONFIG_HOME:-$HOME/.config}/zsh"

This tells ZSH where the ZSH dotfiles are.

Important note

It is possible that your system might not be happy with this. I have yet to fully work out the little issues that I have with making a consistent environment across all of my user session.

This might result in a need to create a system of linked environment files to ensure that everything can access the environment variables that are meant to be set.

Issues

This is a personal project and is unlikely to be maintained in a professional manner. If you do find any technical issues during your usage of this config then feel free to open a GitHub issue. Please remember that GitHub issues are not a forum nor a place for you to ask questions not related to technical issues, and it is completely up to my own discretion what issues I handle and which ones I close.

General overview

The main goals for this configuration are look good, work good, and be quick. The less things getting in my way the better.

This is why I have made opinionated decisions about what options to enable and how it works.

Notable features

• Edit the command line in $EDITOR by pressing C-x C-e
• Fully configured completion
• Automatic typo repair
• vi mode enabled
• Automatic use of the directory stack popd to go back whence you came
• Smart history
• Plug-ins chosen for greatness
• Extended Globbing enabled.
• 10 second thinking time enforced for big deletes
• Expanded directories automatically have / appended
• Allow comments in interactive mode (this may be useful to mark history items)
• Neaten paths like ../foo/.. to .. (ChaseDots)

Breakdown

The following sections break down what is in the repository and what function it does.

Modules

./aliases

This module features aliases that I find useful or ones that improve existing tools. Any alias that uses external tools uses the has function to disable it when the tool isn't installed.

Current aliases:

• ls => exa --icons --group-directories-first (see: Exa Website )
• xopen => xdg-open
• cls => clear; ls
• se => scriptedit (wrapper script for fzf and nvim)
• yt => youtube-dl
• yta => youtube-dl --ignore-config --add-metadata --ignore-errors --extract-audio --format "bestaudio/best"
• cp => cp --interactive --verbose
• mv => mv --interactive --verbose
• rm => rm --interactive=once --verbose
• mkd => mkdir --parents --verbose
• diff => diff --color=auto
• grep => grep --color=auto
• ip => ip --colour=auto
• vw => nvim -c VimwikiIndex
• ws => wineselect (script to choose and set wine-prefix)
• zero => dirs -c && clear

File associations

This module is also responsible for in terminal file associations. Given a file with a particular extension ZSH can open it with the appropriate program. tex, html, and md files are mapped to either nvim, vim, or vi in that order of preference. pdf files are mapped to zathura when it's installed.

./completion

This file configures the powerful completion engine of ZSH. Documenting this here would be a waste since the file has decent comments. For more information on ZSH completion see man zshcompsys

./dir_aliases

This file uses hash to add entries into the named directory hash table. (See: man zshbuiltins) This gives the effect of these "aliases" that represent directories.

• ~dx => $HOME/Documents
• ~dl => $HOME/Downloads
• ~cn => ${XDG_CONFIG_HOME:-$HOME/.config}
• ~px => $HOME/Pictures
• ~pr => $HOME/Projects

./greet

This file gets executed at the end of zshrc to provide a little message on startup.

./history

This file configures the ZSH history system.

This makes a few changes:

• Moves history to ${XDG_STATE_HOME/zsh/history}
• Ignores duplicate entries
• Ignore entries starting with a space
• Compacts whitespace
• Never saves duplicates
• Ignores duplicates when searching history
• Requires you press enter after expanding !!

'./hooks'

This file loads hook functions found in './hooks.d' and makes it easier to assign hooks where necessary.

./keyboard

This file uses zkbd(see man zshcontrib) to get information about your keyboard and how your terminal handles it. This can fix issues with keys not being recognised in programs.

./prompt

This file configures the prompts, and yes there's two. ZSH has both a left and right prompt and I use both of them.

Left prompt

The left prompt shows user, hostname, current directory, and the status of the last command.

Right prompt

The right prompt shows the status of git repository information while you're in one.

precmd

This file also sets the precmd hook to set the terminal title (for terminals which support the escape codes that do this.)

zshrc

This is the true zshrc file with .zshrc a symbolic link to this file. This makes it a little easier to edit the file since you can actually see it in ls and in editors.

This file draws together the modules and actually makes settings apply.

Functions

This configuration defines and loads some functions, some of which are helper functions used in the configuration.

CleanTmp

Function called during exit to clean a local tmp directory (~/tmp).

has

Just a wrapper for calling command -v $COMMAND. This function gets used to check for external tools.

setTermTitle

This function gets used in the prompt to set the terminal title. It makes use of escape sequences to control the terminal and might have issues on rare or unusual terminals.

tempPersist

This function controls if the local tmp directory (~/tmp) will persist across sessions or not.

_dotnet

This completion function that tells the completion engine how to complete dotnet commands.