bruvv.zsh_antigen

Tested on Ubuntu 22.04, macOS 13.0.1

Zero-knowledge install

If you using Ubuntu or Debian and not familiar with Ansible, you can just execute install.sh on target machine:

curl https://raw.githubusercontent.com/bruvv/ansible-role-zsh/main/install.sh | bash

Then configure terminal application.

Includes

Features

customize powerlevel10k theme prompt segments and colors
add custom prompt elements from yml
custom zsh config with ~/.zshrc.local or /etc/zshrc.local
load /etc/profile.d scripts
install only plugins that useful for your machine. For example, plugin docker will not install if you have not Docker

1.5 mins demo

Color schemes

colors demo

Demo install in Vagrant

You can test work of role before install in real machine. Just execute vagrant up, then vagrant ssh for enter in virtual machine.

Note: you cannot install vagrant on VPS like Digital Ocean or in Docker. Use local machine for it. Download and install vagrant for your operating system.

Install for real machine

Zero-knowledge install: see above.

Multiuser shared install

If you have 10+ users on host, probably you don't want manage tens of configurations and thousands of files.

In this case you can deploy single zsh config and include it to all users.

It causes some limitations:

Users have read only access to zsh config
Users cannot disable global enabled bundles
Possible bugs such cache write permission denied
Possible bugs with oh-my-zsh themes

For install shared configuration you should set zsh_shared: yes. Configuration will install to /usr/share/zsh-config, then you just can include to user config:

source /usr/share/zsh-config/.zshrc

You can still provision custom configs for several users.

Configure

You should not edit ~/.zshrc! Add your custom config to ~/.zshrc.local (per user) or /etc/zshrc.local (global). .zshrc.local will never touched by ansible.

Configure terminal application

Download powerline fonts, install font that you prefer. You can see screenshots here.
Set color scheme.

Personaly, I prefer Solarized Dark color sceme, Droid Sans Mono for Powerline in iTerm and DejaVu Sans Mono in Putty.

iTerm

Profiles - Text - Change Font - select font "for Powerline"

Profiles - Colors - Color Presets... - select Solarized Dark

Putty

Settings - Window - Appearance - Font settings

You can download Solarized Dark for Putty.

Gnome Terminal

gnome-terminal have built-in Solarized Dark, note that you should select both background color scheme and palette scheme.

Hotkeys

You can view hotkeys in roles/zsh-install/defaults/main.yml, zsh_hotkeys.

Sample hotkey definitions:

- { hotkey: "^r", action: "fzf-history" }
# with dependency of bundle
- {
    hotkey: "`",
    action: autosuggest-accept,
    bundle: zsh-users/zsh-autosuggestions,
  }

Useful to set autosuggest-accept to ` hotkey, but it conflicts with Midnight Commander (break Ctrl+O subshell).

You can add your custom hotkeys without replace default hotkeys with zsh_hotkeys_extras variable:

zsh_hotkeys_extras:
  - { hotkey: "^[^[[D", action: backward-word } # alt+left
  - { hotkey: "^[^[[C", action: forward-word } # alt+right
  # Example <Ctrl+.><Ctrl+,> inserts 2nd argument from end of prev. cmd
  - { hotkey: "^[,", action: copy-earlier-word } # ctrl+,

Aliases

You can use aliases for your command with easy deploy. Aliases config mostly same as hotkeys config:

zsh_aliases:
  - { alias: 'dfh', action: 'df -h | grep -v docker' }
# with dependency of bundle and without replace default asiases
- zsh_aliases_extra
  - { alias: 'dfh', action: 'df -h | grep -v docker', bundle: }

Default hotkeys from plugins

→ - accept autosuggestion
Ctrl+Z - move current application to background, press again for return to foreground
Ctrl+G - jump to bookmarked directory. Use mark in directory for add to bookmarks
Ctrl+R - show command history
Ctrl+@ - show all fzf-widgets
Ctrl+@,C - fzf-change-dir, press fast!
Ctrl+\ - fzf-change-recent-dir
Ctrl+@,G - fzf-change-repository
Ctrl+@,F - fzf-edit-files
Ctrl+@,. - fzf-edit-dotfiles
Ctrl+@,S - fzf-exec-ssh (using your ~/.ssh/config)
Ctrl+@,G,A - fzf-git-add-file
Ctrl+@,G,B - fzf-git-checkout-branch
Ctrl+@,G,D - fzf-git-delete-branches

Configure bundles

You can check default bundles in roles/zsh-install/defaults/main.yml. If you like default bundles, but you want to add your bundles, use zsh_antigen_bundles_extras variable (see example playbook above). If you want to remove some default bundles, you should use zsh_antigen_bundles variable.

Format of list matches antigen. All bellow variants valid:

- docker # oh-my-zsh plugin
- zsh-users/zsh-autosuggestions # plugin from github
- zsh-users/[email protected] # plugin from github with fixed version
- ~/projects/zsh/my-plugin --no-local-clone # plugin from local directory

Note that bundles can use conditions for load. There are two types of conditions:

Command conditions. Just add command to bundle:
```
- { name: docker, command: docker }
- name: docker-compose
  command: docker-compose
```
Bundles docker and docker-compose will be added to config only if commands exists on target system.

When conditions. You can define any ansible conditions as you define in when in tasks:

# load only for zsh >= 4.3.17
- name: zsh-users/zsh-syntax-highlighting
  when: "{{ zsh_version is version_compare('4.3.17', '>=') }}"
# load only for macOS
- { name: brew, when: "{{ ansible_os_family != 'Darwin' }}" }