Home

Awesome

ZSH Quickstart Kit

License Build Status Awesomebot Megalinter GitHub last commit (branch)

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Table of Contents

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Announcement

I've switched the quickstart kit to use zgenom instead of zgen. This should be a painless update since zgenom is a superset of zgen.

Installation

Prerequisites

Fonts

This quickstart includes the powerlevel10k ZSH theme, which requires a Powerline-compatible font in your terminal to display status glyphs. Powerline-compatible fonts include many useful glyphs, including the nice branch icon that the theme in this .zshrc uses.

Here are a few good Powerline-compatible fonts:

OS-specific setup

fzf

To enable the enhanced history search, you'll need to install fzf. Manual install instructions can be found at fzf and os-specific instructions below.

macOS

<details><summary>macOS instructions</summary>
  1. Download iTerm2 from http://www.iterm2.com (optional). In my opinion, it is considerably nicer than the stock Terminal application that comes with macOS. There is an RCE flaw in all versions of iTerm 2 before 3.3.6, so update if you're using an affected version.
  2. Install the current version of Homebrew from http://brew.sh/.
  3. Install GNU Stow with brew install stow
  4. Homebrew has a newer version of zsh than the one Apple shipped with the OS before 11.6, so brew install zsh to install it.
  5. Switch your shell to zsh if necessary - Apple has defaulted the shell for new users to zsh since macOS Catalina (10.15):
    1. System Preferences -> Users & Groups.
    2. Unlock the preferences
    3. Select your user
    4. Select advanced options
    5. Set your login shell to /bin/zsh (or /usr/local/bin/zsh if you decided to use the version packaged by brew)
  6. Install some Powerline-compatible or NerdFont fonts from one of the links in the Fonts section above.
    1. In iTerm 2, go to Preferences->Profile in your iTerm 2 preferences, then select one of the Powerline-compatible fonts you just installed.
    2. Make sure you also specify a Powerline-compatible font for non-ASCII in your iTerm 2 preferences or the prompt separators and branch glyphs will show up garbled.
  7. Install fzf
    1. Install fzf with brew install fzf
    2. Run the sh "$(brew --prefix fzf)/install" command to configure fzf
    3. Press Enter (y default) for all questions except Do you want to update your shell configuration files? ([y]/n). For this question, select n and press Enter.
</details>

Linux

<details><summary>Linux instructions</summary>
  1. Switch your shell to zsh with chsh -s /bin/zsh
  2. Install GNU Stow - sudo yum install -y stow on Red Hat / CentOS systems, sudo apt-get -y install stow on Debian / Ubuntu.
  3. Install fzf - sudo apt-get install -y fzf on Debian / Ubuntu, do a manual install on Red Hat / Centos - instructions are at fzf.
  4. Install the patched font in a valid X font path. Valid font paths can be listed with xset q: mv YourChosenPowerlineFont.otf ~/.fonts
  5. Update the font cache for the path the font was installed in (root privileges may be needed for updating the font cache for some paths): fc-cache -vf ~/.fonts/

After installing a Nerdfont or Powerline-compatible font, you will need to configure your terminal emulator to use your selected Powerline-compatible font. The name of the correct font usually ends with for Powerline.

If the Powerline symbols can't be seen or are garbled, try closing all instances of the terminal emulator. The X Server may also need to be restarted for the new font to load correctly.

If you still can’t see the new fonts, confirm that the font has been installed to a valid X font path.

If you get garbled branch glyphs, make sure there isn't a separate font setting for non-ASCII characters in your terminal application that you also need to set to use a Powerline-compatible font. Konsole needs to be set to use UTF-8 encoding, for example.

</details>

Set up Zgenom and the starter kit

Now that your fonts and default shell have been set up, install zgenom and the dotfiles from this starter kit repository.

  1. Install Zgenom
    1. cd ~
    2. git clone https://github.com/jandamm/zgenom.git
  2. Install the starter kit
    1. cd ~
    2. git clone https://github.com/unixorn/zsh-quickstart-kit.git
  3. Configure zsh by symlinking the .zshrc, .zsh-functions, .zgen-setup and .zsh_aliases from this repository into your ~.
    1. You can do this with stow by:
      1. cd zsh-quickstart-kit
      2. stow --target=~ zsh. If you have issues using ~ as a target, do stow --target="$HOME" zsh. If you still have errors, symlink the files in the kit's zsh directory into your home directory.

The .zshrc, .zsh_aliases & .zsh_functions files included in this kit enable the plugins listed below.

Contents of the kit

The zsh-quickstart-kit configures your ZSH environment so that it includes:

Included plugins

The quickstart kit also uses zgenom to load oh-my-zsh and these plugins:

Customizing the kit

Behavior toggles

Running the following commands will toggle behavior the next time you start a shell session:

zqs

As of 2021-11-13, I've added a zqs command to start exposing some of the configurable parts in a more user-friendly way. The zqs command has the following subcommands:

zqs check-for-updates

Updates the quickstart kit if it has been longer than seven days since the last update.

zqs disable-bindkey-handling

Disable bindkey setup and alias expansion in the quickstart .zshrc so people can use plugins like globalias to handle it instead.

zqs disable-1password-agent

Disable using 1Password's ssh agent

zqs enable-1password-agent

Enable using 1Password's ssh agent starting with the next new ZSH session. This is the default behavior when op is in your $PATH.

zqs enable-bindkey-handling

Let the quickstart's .zshrc configure bindkey setup and alias expansion. This is the default behavior.

zqs disable-diff-so-fancy

Stop loading the diff-so-fancy plugin starting with the next ZSH session.

zqs enable-diff-so-fancy

Start loading the diff-so-fancy plugin starting with the next ZSH session. This is the default behavior.

zqs disable-omz-plugins

Set the quickstart to not include any oh-my-zsh plugins from the standard plugin list. Loading omz plugins can make terminal startup significantly slower.

zqs enable-control-c-decorator

Set the quickstart to create a TRAPINT handler in future zsh sessions to also display control-C when you type control-c. This is the default behavior.

zqs disable-control-c-decorator

Set the quickstart to not create the TRAPINT handler to display control-C when you type control-c in future zsh sessions.

zqs enable-omz-plugins

Sets the quickstart to include the oh-my-zsh plugins from the standard plugin list.

zqs enable-ssh-askpass-require

Enable the quickstart to prompt for your ssh passphrase on the command line.

zqs disable-ssh-askpass-require

The quickstart will prompt for your ssh passphrase via a gui program. Default behavior.

zqs-disable-ssh-key-listing

Don't print the loaded ssh keys when creating a new session.

zqs-enable-ssh-key-listing

Print the loaded ssh keys when creating a new session. This is the default behavior.

zqs-disable-ssh-key-loading

Don't load ssh keys when creating a new session. Useful if you're storing your private keys in a yubikey.

zqs-enable-ssh-key-loading

Load missing ssh private keys when creating a new session. This is the default behavior.

zqs-disable-zmv-autoloading

Don't run autoload -U zmv when creating a new session.

zqs-enable-zmv-autoloading

Run autoload -U zmv when creating a new session. This is the default behavior.

`zqs-disable-zsh-profiling

Disable ZSH's profiler. This is the default.

`zqs-enable-zsh-profiling

Turn on ZSH's profiler

zqs selfupdate

Force an immediate update of the quickstart kit.

zqs update

Update the quickstart kit and all your plugins.

zqs update-plugins

Updates all your plugins.

zqs cleanup

Cleanup unused plugins after removing them from the list

zqs get-setting

zqs get-setting NAME [OPTIONAL default value] prints the value of a zqs setting, or if unset and a default value was passed, the specified default.

zqs set-setting

zqs set-setting NAME VALUE writes a setting.

zqs delete-setting

zqs delete-setting NAME deletes a setting from zqs's crude parameter store.

Functions and Aliases

Customizing with ~/.zshrc.d

The .zshrc included in this kit will automatically source any files it finds in ~/.zshrc.d. This happens after plugins are loaded. If you need to set variables or aliases before plugins are loaded, create files in ~/.zshrc.pre-plugins.d.

This makes it easy for you to add extra functions and aliases without having to maintain a separate fork of this repository and allows you to configure the behavior of some of the plugins by setting environment variables.

The files will be sourced in alphanumeric order after loading all the plugins, and I suggest you use a naming scheme of 001-onething, 002-something-else etc., to ensure they're loaded in the order you expect.

I like a plugin, but some of the aliases and functions it installs overwrite other commands or aliases I use

Make a file in ~/.zshrc.d named something like 999-reset-aliases. Because files in ~/.zshrc.d are loaded after all the ZSH plugins, you can add lines like unalias xyzzy to remove an alias named xyzzy, or unset -f abcd to remove a function named abcd.

Once you've cleared all the unwanted aliases and functions, you can add new ones with your preferred names.

ZSH options

The quickstart kit does an opinionated (i.e., my way) setup of ZSH options and adds some functions and aliases I like on my systems. I don't want you to have to maintain a separate fork if you don't like them and/or want to add your own, so the kit allows you to override or add behavior by creating fragment files that it will load during session startup.

Fragment file directories

You can customize the quickstart by adding files to its various zshrc.d directories.

If you want to set variables before the quickstart starts loading plugins to alter their behavior, stick your fragment files in ~/.zshrc.pre-plugins.d.

After the quickstart sets up its aliases, functions, plugins and ZSH options, it will source every fragment file in ~/.zshrc.d.

To make it easier to have macOS, FreeBSD or Linux-specific settings tweaks, the quickstart also supports OS-specific pre & post .zshrc.d directories. If you want a file to only be sourced on a single OS, the quickstart also checks for .zshrc.pre-plugins.$(uname).d and ~/.zshrc.$(uname).d during loading.

Self-update Settings

The quickstart kit will automatically check for updates every seven days. If you want to change the interval, set QUICKSTART_KIT_REFRESH_IN_DAYS in a file in ~/.zshrc.d. If you're going to disable self-updating entirely, add unset QUICKSTART_KIT_REFRESH_IN_DAYS in a file in ~/.zshrc.d.

Customizing the plugin list

I've included what I think is a good starter set of ZSH plugins in this repository. However, everyone has their preferences for their environment.

To make things easier to customize without users having to maintain their own forks, the kit provides two ways to customize the list of plugins it will load.

You can either add a fragment file to ~/.zshrc.add-plugins.d, or you can make a ~/.zsh-quickstart-local-plugin file.

Using fragment files

If all you want to do is add plugins to the standard list and you want to still automatically get any new changes I make to that standard list (new plugins, new locations when existing plugins are moved, etc) then adding a file into ~/.zshrc.add-plugins.d with your extra plugins listed as zgenom load githubuser/pluginrepo (one line per plugin) is the way to go. The kit will load its plugins, then add yours on the end. You can add separate files with plugins in the ~/.zshrc.add-plugins.d directory - my personal use case is having one file with all the plugins I use everywhere, and one that has extra plugins I only need on my work machines. This is the easiest option.

Complete plugin list replacement

If you don't care about future changes to the kit's plugins and want to fully replace the built-in list, then create a ~/.zsh-quickstart-local-plugins file. When the kit detects a file named ~/.zsh-quickstart-local-plugins, its .zshrc will source that instead of running the load-starter-plugin-list function defined in ~/.zgen-setup.

Using ~/.zsh-quickstart-local-plugins is not additive. It will completely replace the kit-provided list of plugins. If you want to just add more plugins, use the fragment file method above.

Creating a .zsh-quickstart-local-plugins from scratch is a pain, so to make customizing your plugin list easier, I've included a .zsh-quickstart-local-plugins-example file at the root of the repository that installs the same plugin list that the kit does by default that you can use as a starting point for your own .zsh-quickstart-local-plugins file.

Copy that to your $HOME/.zsh-quickstart-local-plugins, change the list, and the next time you start a terminal session, you'll get your plugin list loaded instead of the kit's defaults.

Disabling zmv

The quickstart automatically autoloads zmv. If you want to disable that so you can configure it with another plugin or on your own, run zqs disable-zmv-autoloading.

Disabling oh-my-zsh

If you don't want zgenom to load the oh-my-zsh defaults, run zqs-disable-omz-plugins.

FAQ

How do I reconfigure the prompt?

You may want to reconfigure your prompt after using it. The quickstart uses the powerlevel10k theme, so you can reconfigure your prompt by running p10k configure.

Powerlevel 10k warns that there is console output during startup

You see a warning during session startup -

[WARNING]: Console output during zsh initialization detected.
When using Powerlevel10k with instant prompt, console output during zsh
initialization may indicate issues.

You can stifle this output by adding typeset -g POWERLEVEL9K_INSTANT_PROMPT=quiet in a fragment file in ~/.zshrc.pre-plugins.d.

I added a new completion plugin, and it isn't working

I've had reports that sometimes you may need to reset your completions after adding a new plugin.

rm ~/.zcompdump*
compinit

I get a git error when I try to update the kit

You try to update the kit, and you get an error similar to this:

From https://github.com/unixorn/zsh-quickstart-kit
0c5bad9..2064c6b master -> origin/master

    755f689...e3f8677 switch-to-zgenom -> origin/switch-to-zgenom (forced update)
    Updating 0c5bad9..2064c6b
    error: Your local changes to the following files would be overwritten by merge:
    zsh/.zshrc
    Please commit your changes or stash them before you merge.
    Aborting

This happens when you edit a file provided by the quickstart kit, in this case, .zshrc. This is annoying, and to let you customize your ZSH settings without being forced to maintain your own fork of the kit, the kit-provided .zshrc will load any files it finds in the various ~/.zshrc.d directories. See Fragment File Directories for more details.

GNU stow is warning that stowing zsh would cause conflicts

You ran stow --target=/Users/YourUsername zsh in the top level of the repo and stow printed the following error:

WARNING! stowing zsh would cause conflicts:
  * existing target is neither a link nor a directory: .zshrc
All operations aborted.

Per @jefheaton, this is caused when trying to replace an existing .zshrc file. He fixed it by closing ~ in Finder so Finder wouldn't create a .DS_Store file, deleting the existing .DS_Store and removing the old .zshrc. You may have to rename it first if ZSH is keeping the file open, then delete it after closing all your Terminal/iTerm 2 windows.

_arguments:comparguments:325: can only be called from completion function

This has been solved by running zgen update or switching to zgenom. New users of the kit should already be running zgenom. Thanks @RonanJackson, for reporting the fix.

Could not open a connection to your authentication agent

Confirm that ssh-agent is running. If not, Rob Montero has a good blog post on setting up ssh-agent on macOS, and here are instructions for starting ssh-agent with systemd on Linux.

I want to pin a plugin version

The plugin standard doesn't include a standard way of determining a version. If you need to pin a version of a plugin, the easiest way to do it is to fork the plugin's repository and then have your ~/.zsh-quickstart-local-plugins refer to that.

If you don't want to maintain a fork, you can also have zgenom load from a local directory. So clone the repository, then add something like

zgenom load ~/path/to/your/copy/of/example.plugin.zsh

Then you can tag working versions, pull from upstream for testing, and if the upstream doesn't work for you, check out your last-working-version tag, and zgenom will use your tagged version instead of the tip of the default branch.

Other Resources

ZSH

Dotfiles in general

dotfiles.github.io/ has a lot of great resources for dotfiles - frameworks for managing them, configurations for editors, and other bootstraps with initial configurations to start from.

Vim

If you're using vim, spf13 is an excellent starter configuration and plugin collection.

Thanks

Many thanks to all the contributors over the years who've helped make the quickstart better.

<a href="https://github.com/unixorn/zsh-quickstart-kit/graphs/contributors"> <img src="https://contributors-img.web.app/image?repo=unixorn/zsh-quickstart-kit" /> </a>

Made with contributors-img.