====== Install ======

<code bash>
# Gentoo
emerge -av zsh-completions gentoo-zsh-completions
# Arch
pacman -Syu zsh
</code>

You may want to take advantage of plugins and themes that are available from [[https://ohmyz.sh/|ohmyz.sh]] ([[https://github.com/robbyrussell/oh-my-zsh|GitHub]]) in which case as user...

<code bash>
sh -c "$(curl -fsSL https://raw.github.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"
</code>

It is worth copying over aliases from `~/.bashrc` or `~/.bash_aliases` to `~/.zshrc` as well as code to Start X if you have any in `~/.bash_profile`.  As I use `~/.bash_aliases` to store my aliases I initially added sourcing it to `~/.zshrc`

<code bash>
echo 'source ~/.bash_aliases' >> ~/.zshrc
</code>



To migrate aliases you need to adopt the syntax used by ZSH, this is explained in detail in the [reference](http://zsh.sourceforge.net/Doc/Release/Shell-Grammar.html#Aliasing).  At some point I'll migrate these to `ZSH_CUSTOM` or `~/.zenv` but careful care is required if you are to use aliases in any scripts as many will run under `/bin/bash` rather than `zsh` so for now I'm keeping everything in `~/.bash_aliases` and sourcing that when starting zsh as it seems to work.
====== Configuration ======

===== Themes =====

Tons to choose from powerline like ones are useful (i.e. [Agnoster](https://gist.github.com/agnoster/3712874) and [AgnosterZak](https://github.com/zakaziko99/agnosterzak-ohmyzsh-theme)), purportedly complete list is [zshthem.es/all](https://zshthem.es/all/).  A very neat feature is to have the Git branch shown with various bits of information about the current status.

Themes I've tried and liked are...

  * [powerlevel9k](https://github.com/bhilburn/powerlevel9k)
  * [powerlevel10k](https://github.com/romkatv/powerlevel10k)
  * [agnoster](https://github.com/agnoster/agnoster-zsh-theme)
  * [agnosterzak](https://github.com/zakaziko99/agnosterzak-ohmyzsh-theme)
  * [bullet-train](https://github.com/caiogondim/bullet-train-oh-my-zsh-theme)
  * [alien](https://github.com/eendroroy/alien) (not actually got this working yet though!)

At some point I intend to set the ZSH theme conditional on the `$HOST` which should in theory make it easier to distinguish which host I'm on.  The most promising for this is the [alien](https://github.com/eendroroy/alien) theme which annoyingly I've not yet got working.


===== Plugins =====

==== Autocompletion ====

Autocompletion is very powerful under `zsh` and extensible.  By default a commands arguments can be tab-completed and there are custom completions for [Git](https://git-scm.com/book/en/v2/Appendix-A%3A-Git-in-Other-Environments-Git-in-Zsh).  One thing I found was that [pass]() which normally has autocompletion for the directory structure of saved passwords didn't work by default.  However, [oh-my-zsh](https://ohmyz.sh/) ships with a [pass plugin](https://github.com/robbyrussell/oh-my-zsh/blob/master/plugins/pass/_pass).  To enable these add the following to your `.zshrc`.

<code bash>
plugins=(
    git
    pass
)
</code>

====== Xfce4 Terminal ======

Many themes that I was trying out used [solarized](https://github.com/altercation/solarized) colours, however by default the [Xfce4 terminal]() didn't support such colours.  I found the [xfce4-terminal-colors-solarized](https://github.com/sgerrand/xfce4-terminal-colors-solarized) package and opted to install and use it.  The installation instructions aren't 100\% explicit and having looked at it I wouldn't recommend blindly over-writing `~/.config/xfce4/terminal/terminalrc` with the dark/light solarized settings.  Rather I would append the lines...

<code bash>
git clone https://github.com/sgerrand/xfce4-terminal-colors-solarized
cat xfce4-terminal-colors-solarized/dark/terminalrc >> ~/.config/xfce4/terminal/terminalrc
</code>

====== Troubleshooting ======

===== Corrupt .zsh_history =====

I encountered this the [solution](https://superuser.com/questions/957913/how-to-fix-and-recover-a-corrupt-history-file-in-zsh) was

<code bash>
mv .zsh_history .zsh_history_bad
strings .zsh_history_bad > .zsh_history
fc -R .zsh_history
</code>

===== Tab-autocomplete =====

I found that tab-autocomplete of commands and directory/file paths became corrupted, the [solution](https://github.com/robbyrussell/oh-my-zsh/issues/3996) was to remove `~/.zcompdump*`.  For this to take effect you have to log out of the shell and back in.

<code bash>
rm -f ~/zcompdump*
</code>
====== Links ======

  * [ZSH reference](http://zsh.sourceforge.net/Doc/Release/zsh_toc.html)
  * [Oh My ZSH!](https://ohmyz.sh/)