jeket / zsh-quickstart-kit

Simple ZSH quickstart for using ZSH, zgenom, oh-my-zsh and a curated list of extra plugins.

ZSH Quickstart Kit

Table of Contents

• Announcement
• Installation
  • Prerequisites
    • Fonts
  • OS-specific setup
    • fzf
    • macOS
    • Linux
  • Set up Zgenom and the starter kit
• Contents of the kit
  • Included plugins
• Customizing the kit
  • Behavior toggles
  • Functions and Aliases
  • I like a plugin, but the aliases it installs overwrite other commands or aliases
  • ZSH options
  • Self-update Settings
  • Changing the plugin list
  • Disabling zmv
  • Disabling oh-my-zsh
• FAQ
  • How do I reconfigure the prompt?
  • I added a new completion plugin and it isn't working
  • I get a git error when I try to update the kit
  • GNU stow complains with a warning that stowing zsh would cause conflicts
  • _arguments:comparguments:325: can only be called from completion function
• Other Resources
  • ZSH
  • Dotfiles in general
  • Vim

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 certain status glyphs. Fonts that are Powerline-compatible include many useful glyphs, including the nice branch icon that the theme in this .zshrc uses.

Here are a few good Powerline-compatible fonts:

• Awesome Terminal Fonts - A family of fonts that includes some nice monospaced Icons.
• Cascadia Code - Microsoft's Cascadia Code
• Fantasque Awesome Font - A nice monospaced font, patched with Font-Awesome, Octoicons and Powerline-Glyphs.
• Fira Mono - Mozilla's Fira type family.
• Hack - Another Powerline-compatible font designed specifically for source code and terminal usage.
• Input Mono - A family of fonts designed specifically for code. It offers both monospaced and proportional fonts and includes Powerline glyphs.
• Iosevka - Iosevka is an open source slender monospace sans-serif and slab-serif typeface inspired by Pragmata Pro, M+ and PF DIN Mono, designed to be the ideal font for programming.
• Monoid - Monoid is customizable and optimized for coding with bitmap-like sharpness at 15px line-height even on low res displays.
• Mononoki - Mononoki is a typeface by Matthias Tellen, created to enhance code formatting.
• Nerd fonts - A collection of over 20 patched fonts (over 1,700 variations) & the fontforge font patcher python script for Powerline, devicons, and vim-devicons: includes Droid Sans, Meslo, AnonymousPro, ProFont, Inconsolta, and many more.
• Powerline patched font collection - A collection of a dozen or so fonts patched to include Powerline gylphs.
• Victor Mono - Victor Mono is a free programming font with semi-connected cursive italics, symbol ligatures (!=, ->>, =>, ===, <=, >=, ++) and Latin, Cyrillic and Greek characters.
• spacemono - Google's new original monospace display typeface family.

OS-specific setup

fzf

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

macOS

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. Please note - 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 with brew install fzf

Linux

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 also 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 cannot be seen, try closing all instances of the terminal emulator. The X Server may also need to be restarted for the new font to correctly load.

If you still can’t see the new fonts then double-check 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.

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 [email protected]:unixorn/zsh-quickstart-kit.git
3. Configure zsh by symlinking the .zshrc, .zsh_aliases and .zsh-completions from this repo into your ~.
   1. You can do this with stow by:
      1. cd zsh-quickstart-kit
      2. stow --target=/Users/YourUsername zsh. Replace /Users/YourUsername with /home/YourUsername if you're on Linux. If you still have errors, symlink the files in zsh 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:

• Automatic periodic updates of both zgenom and your plugins
• Cross-session shared history so commands typed in one terminal window can be seen and searched in all your other zsh sessions on the same machine.
• Automatic deduplication of your command history.
• Many more tab completions, courtesy of the zsh-users/zsh-completions repository, and periodic updating to tip of master of that repository so you get updates to the extra tab completions.
• Supercharged command history search with fzf.
• Syntax highlighting at the command line.
• Tab completion of Rakefile targets.
• Enabling oh-my-zsh-compatible plugins and themes (via the zgenom framework).
• Various helper functions for interacting with macOS' clipboard, audio volume, Spotlight and Quicklook. For your convenience, these will only load if you are on a macOS machine so you can use the same plugin list on any *NIX system.
• If you've installed iTerm2's shell integration, it will automatically be loaded during shell startup.

Included plugins

• chrissicool/zsh-256color - Sets your terminal to 256 colors if available.
• djui/alias-tips - Warns you when you have an alias for the command you just typed, and tells you what it is.
• peterhurford/git-it-on.zsh - Opens your current repo on github, in your current branch.
• RobSis/zsh-completion-generator - Adds a tool to generate ZSH completion functions for programs missing them by parsing their --help output. Note that this doesn't happen dynamically, you'll have to explicitly run it to create a completion for each command missing one.
• sharat87/pip-app - A set of shell functions to make it easy to install small apps and utilities distributed with pip.
• skx/sysadmin-util - A collection of scripts useful for sysadmins.
• srijanshetty/docker-zsh - Adds completions for docker.
• stackexchange/blackbox - Tom Limoncelli's tool for storing secret information in a repository with gnupg encryption, automatically decrypting as needed.
• supercrabtree/k - k is a directory lister that also shows git status on files & directories.
• unixorn/autoupdate-zgenom - Adds autoupdate (for both zgenom itself, and your plugins) to zgenom.
• unixorn/bitbucket-git-helpers - Adds git helper scripts for bitbucket.
• unixorn/fzf-zsh-plugin - This enables fzf-powered history search.
• unixorn/git-extra-commands - A collection of extra helper scripts for git.
• unixorn/jpb.zshplugin - Some of my standard aliases & functions.
• unixorn/rake-completion.zshplugin - Reads the Rakefile in the current directory so you can tab complete the Rakefile targets.
• unixorn/tumult.plugin.zsh - Adds macOS-specific functions and scripts. This plugin only adds itself to your $PATH if you're running macOS to allow you to use the same plugin list on macOS and other systems.
• zsh-autosuggestions - Adds fish-like autosuggestions to your ZSH sessions.
• zsh-users/zsh-completions - Tab completions for many more applications than come standard with ZSH.
• zsh-users/zsh-history-substring-search - Better history search.
• zsh-users/zsh-syntax-highlighting - Syntax highlighting as you type.

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

• aws
• brew - only loaded on macOS
• chruby
• colored-man
• git
• github
• osx - this will only be loaded on macOS
• pip
• python
• rsync
• screen
• sudo
• vagrant

Customizing the kit

Behavior toggles

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

• zsh-quickstart-disable-omz-plugins - Makes the stock quickstart not load any of the oh-my-zsh plugins it would normally use. You can re-enable them for new shell sessions with zsh-quickstart-enable-omz-plugins.

• Prompt selectors - We now use the powerlevel10k prompt. I won't change the prompt out from under people without a way for them to get the old behavior, so there are commands to switch back and forth.

  • zsh-quickstart-select-powerlevel10k - Switch to the powerlevel10k prompt now used as the kit's default.
  • zsh-quickstart-select-bullet-train - Switch back to the bullet-train prompt originally used in the kit.

• You can disable printing the list of ssh keys by setting DONT_PRINT_SSH_KEY_LIST in a file in ~/.zshrc.d.

• bash prints ^C when you're typing a command and control-c to cancel, so it is easy to see it wasn't executed. By default, ZSH doesn't print the ^C. I like seeing the ^C, so by default the quickstart traps SIGINT and prints the ^C. You can disable this by exporting ZSH_QUICKSTART_SKIP_TRAPINT='false' in one of the files in ~/.zshrc.d.

Functions and Aliases

The .zshrc included in this kit will automatically source any files it finds in ~/.zshrc.d.

This is to make it easy for you to add extra functions and aliases without having to maintain a separate fork of this repository, and also allows you to configure 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 the aliases it installs overwrite other commands or aliases

Make a file in ~/.zshrc.d named something like 999-reset-aliases. Since those are loaded after all the ZSH plugins, you can add lines like unalias xyzzy to remove an alias named xyzzy. Once you've cleared all the aliases you don't want, you can add new ones with the names you prefer.

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. However, ~/.zshrc.d is processed after the quickstart sets its aliases, functions and ZSH options, so if you don't care for something as set up in the quickstart, you can override the offending item in a shell fragment file there.

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 want to disable self updating entirely, add unset QUICKSTART_KIT_REFRESH_IN_DAYS in a file in ~/.zshrc.d.

Changing the plugin list

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

To make the list easier to customize without having to maintain a separate fork of the quickstart kit, if you create a file named ~/.zsh-quickstart-local-plugins, the .zshrc from this starter kit 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.

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

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, create a file named .zsh-quickstart-no-zmv in your home directory.

Disabling oh-my-zsh

If you don't want zgenom to load the oh-my-zsh defaults, create .zsh-quickstart-no-omz in your home directory.

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.

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

I've had reports that sometimes you 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 in order to let you customize your ZSH settings without having to maintain your own fork, the kit-provided .zshrc will load any files it finds in ~/.zshrc.d.

GNU stow complains with a 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 then removing the old .zshrc. You may have to rename it first if ZSH is keeping the file open, then deleting 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.

Other Resources

ZSH

• For a list of other ZSH plugins, completions and themes you might like to use, check out my awesome-zsh-plugins list. It also contains a list of other ZSH tutorials and starter kits.
• Justin Garrison has a good repo that details Mastering 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.