Ansible Role: ZSH

Deprecated: This role has been moved to a Collection, check out the new version here.

This is a straightforward role to install and configure the zsh-shell on Linux.

The tasks supported include:

• Installing zsh with chosen packages
• Making zsh the default shell for selected users
• Optionally sharing configuration files

This role is designed to be simple, uses the standard package manager, and has minimal unnecessary additions. If you encounter any issues, feel free to report them.

Preparation

Use Ansible Galaxy to install this role.

ansible-galaxy install patbec.zsh

Variables

Here are the default variables used in this playbook.

Note: The unit test fails if the zsh_executable is a symbolic link.

The zsh_users_config property is structured like this:

zsh_users_config:
  - template: "zshrc.j2"
    filepath: "$HOME/.zshrc"

This example shares a .zshrc file for a user. Ansible will look for the zshrc.j2 file in your template folder.

Paths

Here are possible paths based on the zsh documentation (5.2 Files).

User-specific Paths

zsh_users_config:
  - template: "zshrc.j2"
    filepath: "$HOME/.zshrc"
  - template: "zshenv.j2"
    filepath: "$HOME/.zshenv"
  - template: "zprofile.j2"
    filepath: "$HOME/.zprofile"
  - template: "zlogin.j2"
    filepath: "$HOME/.zlogin"
  - template: "zlogout.j2"
    filepath: "$HOME/.zlogout"

The copying of files happens in each user's context.

System Paths

zsh_system_config:
  - template: "zshrc.j2"
    filepath: "/etc/zshrc"
  - template: "zshenv.j2"
    filepath: "/etc/zshenv"
  - template: "zprofile.j2"
    filepath: "/etc/zprofile"
  - template: "zlogin.j2"
    filepath: "/etc/zlogin"
  - template: "zlogout.j2"
    filepath: "/etc/zlogout"

Examples

Here are some examples of using this role.

1. Basic
   Install zsh and set it as the default shell for the ansible user.
2. Multiple users
   Install zsh and set it as the default shell for a list of users.
3. User-defined config file
   Share a custom .zshrc for a list of users.
4. Custom dependencies
   Share a custom .zshrc file with a package.
5. Extra functions
   Share a custom .zshrc with autosuggestions and syntax-highlighting.
6. Complete
   Full example of a zsh shell configuration.^{Sample Preview}

Basic

Install zsh and set it as the default shell for the ansible_user.

• Install the zsh package.
• Set zsh as the default shell for ansible_user.

- name: zsh
  hosts: all
  roles:
    - patbec.zsh
  tasks:
    ansible.builtin.debug:
        msg: "ZSH has been installed and set as default for the user {{ ansible_user }}."

Multiple users

Install zsh and set it as the default shell for a list of users.

• Install the zsh package.
• Set zsh as the default shell for specified users.

- name: zsh
  hosts: all
  vars:
    zsh_users:
      - lorem
      - ipsum
  roles:
    - patbec.zsh
  tasks:
    ansible.builtin.debug:
        msg: "ZSH was installed and set as default for 2 users."

User-defined config file

Share a custom .zshrc file for a predefined list of users.

• Install the zsh package.
• Set zsh as the default shell for the specified users.
• Share a custom .zshrc for each user.

- name: zsh
  hosts: all
  vars:
    zsh_config_backup: false
    zsh_config_overwrite: true

    zsh_users:
      - lorem
      - ipsum

    zsh_users_config:
      - template: "zshrc.j2"
        filepath: "$HOME/.zshrc"

  roles:
    - patbec.zsh
  tasks:
    ansible.builtin.debug:
        msg: "ZSH was installed and a custom file was shared."

Content for zshrc.j2 in your templates folder:

{% if zsh_config_overwrite %}
#
# {{ ansible_managed }}
#
{% endif %}

# Add your content here.

Custom dependencies

Share a custom .zshrc file with an additional package.

• Install the zsh package.
• Set zsh as the default shell for the specified users.
• Share a custom .zshrc for each user.
• Install a new dependency.

- name: zsh
  hosts: all
  vars:
    zsh_config_backup: false
    zsh_config_overwrite: true

    zsh_users:
      - lorem
      - ipsum

    zsh_users_config:
      - template: "zshrc.j2"
        filepath: "$HOME/.zshrc"

    zsh_dependencies:
      - exa
  roles:
    - patbec.zsh
  tasks:
    ansible.builtin.debug:
        msg: "ZSH has been installed and exa is used to list files."

Content for zshrc.j2 in your templates folder:

{% if zsh_config_overwrite %}
#
# {{ ansible_managed }}
#
{% endif %}

alias ls='exa --group-directories-first'
alias ll='exa --group-directories-first --all --long --binary --group --classify --grid'
alias la='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale'
alias lx='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale --extended'

exa is an improved file lister that offers more features and better defaults, using colors to distinguish file types and metadata.

Extra functions

Share a custom .zshrc with autosuggestions and syntax-highlighting functions.

• Install the zsh package.
• Set zsh as the default shell for the specified users.
• Share a custom .zshrc for each user.
• Install autosuggestions and syntax-highlighting.

- name: zsh
  hosts: all
  vars:
    zsh_config_backup: false
    zsh_config_overwrite: true

    zsh_users:
      - lorem
      - ipsum

    zsh_users_config:
      - template: "zshrc.j2"
        filepath: "$HOME/.zshrc"

    zsh_dependencies:
      - zsh-autosuggestions
      - zsh-syntax-highlighting
  roles:
    - patbec.zsh
  tasks:
    ansible.builtin.debug:
        msg: "ZSH was installed and additional functions were enabled."

Content for zshrc.j2 in your templates folder:

{% if zsh_config_overwrite %}
#
# {{ ansible_managed }}
#
{% endif %}

autoload colors && colors

source  /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source  /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

Complete

Full configuration example for a zsh shell.

• Install the zsh package.
• Set zsh as the default shell for the specified users.
• Share a custom .zshrc for each user.
• Install autosuggestions, syntax-highlighting, and exa.
• Configure history, colors, and cd settings.

- name: zsh
  hosts: all
  vars:
    zsh_config_backup: false
    zsh_config_overwrite: true

    zsh_users:
      - lorem
      - ipsum

    zsh_users_config:
      - template: "zshrc.j2"
        filepath: "$HOME/.zshrc"

    zsh_dependencies:
      - exa
      - zsh-autosuggestions
      - zsh-syntax-highlighting

    zsh_additional_lines: ""
  roles:
    - patbec.zsh
  tasks:
    ansible.builtin.debug:
        msg: "ZSH was installed."

Content for zshrc.j2 in your templates folder:

{% if zsh_config_overwrite %}
#
# {{ ansible_managed }}
#
{% endif %}

autoload colors && colors

PROMPT="%(?:%{$fg_bold[green]%}➜ :%{$fg_bold[red]%}➜ )"
PROMPT+=" %{$fg[cyan]%}%c%{$reset_color%} "

source  /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source  /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh

alias ls='exa --group-directories-first'
alias ll='exa --group-directories-first --all --long --binary --group --classify --grid'
alias la='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale'
alias lx='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale --extended'

HISTFILE="$HOME/.zsh_history"
HISTSIZE=50000
SAVEHIST=50000

setopt INC_APPEND_HISTORY
setopt AUTOCD

{% if zsh_additional_lines is defined %}
#
# Host specific additions
#
{{ zsh_additional_lines }}
{% endif %}

Preview

Here’s what this configuration looks like: _{You can find the used ANSI console colors here.}

License

This project is licensed under MIT - See the LICENSE file for more details.

↑ Back to top