Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/viasite-ansible/ansible-role-zsh

Setup antigen with oh-my-zsh, powerlevel10k theme, fzf, autosuggestions, syntax-highlighting
https://github.com/viasite-ansible/ansible-role-zsh

ansible-galaxy ansible-role fzf oh-my-zsh powerlevel9k zsh zsh-autosuggestions zsh-command-time zsh-syntax-highlighting

Last synced: 30 days ago
JSON representation

Setup antigen with oh-my-zsh, powerlevel10k theme, fzf, autosuggestions, syntax-highlighting

Awesome Lists containing this project

README 

        
Tested on Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, MacOS 14.4.



Tested long time ago: Ubuntu 18.04, MacOS 10.12, CentOS 8



**For upgrade from viasite-ansible.zsh 1.x, 2.x to 3.0 see [below](#upgrade).**



## Zero-knowledge install:

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

```

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

```

It will install pip3, ansible and setup zsh for root and current user.



## MacOS zero-knowledge install:

Requirements: brew, python. Asks user's password. [install-macos.sh](install-macos.sh) will install ansible, and setup zsh for current user and optionally for root:

```

curl https://raw.githubusercontent.com/viasite-ansible/ansible-role-zsh/master/install-macos.sh | bash

```



Then [configure terminal application](#configure-terminal-application).



## Includes:

- zsh

- [antigen](https://github.com/zsh-users/antigen)

- [oh-my-zsh](https://github.com/robbyrussell/oh-my-zsh)

- [powerlevel9k theme](https://github.com/bhilburn/powerlevel9k)

- [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions)

- [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting)

- [unixorn/autoupdate-antigen.zshplugin](https://github.com/unixorn/autoupdate-antigen.zshplugin)

- [sorenson-axial/fzf-widgets](https://github.com/sorenson-axial/fzf-widgets)

- [urbainvaes/fzf-marks](https://github.com/popstas/urbainvaes/fzf-marks)



## Features

- customize powerlevel9k theme prompt segments and colors

- default colors tested with solarized dark and default grey terminal in putty

- 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

![1.5 mins demo](https://github.com/popstas/popstas.github.io/blob/master/images/2017-03/ansible-role-zsh-demo.gif?raw=true)



## Color schemes

![colors demo](https://github.com/popstas/popstas.github.io/blob/master/images/2017-03/ansible-role-zsh-colors.gif?raw=true)



## Midnight Commander Solarized Dark skin

If you are using Solarized Dark scheme and `mc`, you should want to install skin, then set `zsh_mc_solarized_skin: yes`



## 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](https://www.vagrantup.com/downloads.html) and install vagrant for your operating system.



## Install for real machine

Zero-knowledge install: see [above](#zero-knowledge-install).



### Manual install



0. [Install Ansible](http://docs.ansible.com/ansible/intro_installation.html).

For Ubuntu:

``` bash

sudo apt update

sudo apt install python3-pip -y

sudo pip3 install ansible

```



1. Download role:

```

ansible-galaxy install viasite-ansible.zsh --force

```



2. Write playbook or use [playbook.yml](playbook.yml):

```

- hosts: all

  vars:

    zsh_antigen_bundles_extras:

      - nvm

      - joel-porquet/zsh-dircolors-solarized

    zsh_autosuggestions_bind_key: "^U"

  roles:

    - viasite-ansible.zsh

```



3. Provision playbook:

```

ansible-playbook -i "localhost," -c local -K playbook.yml

```



If you want to provision role for root user on macOS, you should install packages manually:

```

brew install zsh git wget

```



It will install zsh environment for ansible remote user. If you want to setup zsh for other users,

you should define variable `zsh_user`:



Via playbook:

```

- hosts: all

  roles:

    - { role: viasite-ansible.zsh, zsh_user: otheruser }

    - { role: viasite-ansible.zsh, zsh_user: thirduser }

```



Or via command:

```

ansible-playbook -i hosts zsh.yml -e zsh_user=otheruser

```



4. Install fzf **without shell extensions**, [download binary](https://github.com/junegunn/fzf-bin/releases)

or `brew install fzf` for macOS.



Note: I don't use `tmux-fzf` and don't tested work of it.



## 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:



## Install for all users

Set `zsh_source_for_all_users: yes`



``` bash

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

1. Download [powerline fonts](https://github.com/powerline/fonts), install font that you prefer.

You can see screenshots [here](https://github.com/powerline/fonts/blob/master/samples/All.md).



2. 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](https://github.com/altercation/solarized/tree/master/putty-colors-solarized).



#### 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 [defaults/main.yml](defaults/main.yml), `zsh_hotkeys`.



Sample hotkey definitions:

``` yaml

- { 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:

``` yaml

zsh_hotkeys_extras:

  - { hotkey: '^[^[[D', action: backward-word } # alt+left

  - { hotkey: '^[^[[C', action: forward-word } # alt+right

  # Example  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:



``` yaml

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 [defaults/main.yml](defaults/main.yml#L37).

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](https://github.com/zsh-users/antigen#antigen-bundle). All bellow variants valid:

``` yaml

- 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:



1. Command conditions. Just add `command` to bundle:

``` yaml

- { 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.



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

``` yaml

# 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' }}" }

```

Note: you should wrap condition in `"{{ }}"`



## Custom config

You can add any code in variable `zsh_custom_before`, `zsh_custom_after`.



- zsh_custom_before - before include antigen.zsh

- zsh_custom_after - before include ~/.zshrc.local



## Upgrade

viasite-ansible.zsh v3.0 introduces antigen v2.0, it don't have backward compatibility to antigen 1.x.



I don't spent much time for smooth upgrade, therefore you probably should do some manual actions:

if powerlevel9k prompt don't loaded after provision role, you should execute `antigen reset`.



After reopen shell all should be done.



### Downgrade to antigen v1

Antigen v2 much faster (up to 2x more faster startup), but if something went wrong, you can downgrade to antigen v1,

see note for zsh 4.3 users below.



### For users with zsh 4.x

Antigen v2 not work on zsh < 5.0, if you use zsh 4.x, please add to you playbook:

``` yaml

zsh_antigen_version: v1.4.1

```



## Known bugs

### `su username` caused errors

See [antigen issue](https://github.com/zsh-users/antigen/issues/136).

If both root and su user using antigen, you should use `su - username` in place of `su username`.



Or you can use bundled alias `suser`.



Also, you can try to fix it, add to `~/.zshrc.local`:

```

alias su='su -'

```

But this alias can break you scripts, that using `su`.