Ecosyste.ms: Awesome

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

Awesome Lists | Featured Topics | Projects

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

A simple role to install and set up the zsh shell on Linux with Ansible.
https://github.com/patbec/ansible-role-zsh

ansible ansible-galaxy ansible-galaxy-role ansible-role automation autosuggestions console galaxy linux sample-code shell syntax-highlighting terminal ubuntu z-shell zsh zsh-shell zshell zshrc

Last synced: about 2 months ago
JSON representation

A simple role to install and set up the zsh shell on Linux with Ansible.

Host: GitHub
URL: https://github.com/patbec/ansible-role-zsh
Owner: patbec
License: mit
Archived: true
Created: 2022-04-15T13:32:42.000Z (over 2 years ago)
Default Branch: master
Last Pushed: 2023-03-26T11:54:44.000Z (over 1 year ago)
Last Synced: 2024-09-19T02:30:26.401Z (about 2 months ago)
Topics: ansible, ansible-galaxy, ansible-galaxy-role, ansible-role, automation, autosuggestions, console, galaxy, linux, sample-code, shell, syntax-highlighting, terminal, ubuntu, z-shell, zsh, zsh-shell, zshell, zshrc
Language: Jinja
Homepage: https://galaxy.ansible.com/patbec/zsh
Size: 55.7 KB
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

zsh console icon

# Ansible Role: ZSH

![Ansible Role](https://img.shields.io/ansible/role/d/58811) ![Ansible Quality Score](https://img.shields.io/ansible/quality/58811) ![GitHub](https://img.shields.io/github/license/patbec/ansible-role-zsh)

## Deprecated: This role has been migrated to a Collection, [here you can find the new version](https://galaxy.ansible.com/bec/shell).

This is a simple role to install and set up the **zsh-shell** on Linux.

The following steps are supported:
- Install zsh with custom packages
- Set zsh as default shell for the specified users
- Optional distribution of configuration files

This role is kept simple, uses the standard package manager and contains minimal overhead. If you have any problems, feel free to create an issue.

## Preparation

Install this role with Ansible Galaxy.
```shell
ansible-galaxy install patbec.zsh
```

## Variables

Default variables in this playbook.

| Name | Description | Default Value |
| -------------------- | ------------------------------------------------------ | -------------------- |
| zsh_config_mode | Default permissions for distributed files. | `0644` |
| zsh_config_backup | Creates a backup before overwriting. | `true` |
| zsh_config_overwrite | Overwrites the existing file if there are differences. | `false` |
| zsh_users_config | A list of zsh files to be distributed for a user. | `[]` |
| zsh_system_config | A list of zsh files to be distributed globally. | `[]` |
| zsh_users | A list of users who should get zsh as default shell. | `{{ ansible_user }}` |
| zsh_dependencies | A list of additional packages to install. | `[]` |
| zsh_executable | Path to the executable. | `/usr/bin/zsh` |

> **Molecule:** Unit test fails if a symbolic link is specified for `zsh_executable`.

The `zsh_users_config` property is a dictionary:

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

This basic example distributes a `.zshrc` for a user. Ansible looks for the `zshrc.j2` file in your `template` folder.

### Paths

Here is a list of possible paths from the [zsh documentation (5.2 Files)](https://zsh.sourceforge.io/Doc/Release/Files.html#Files-1).

#### Users

```yaml
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 copy operation is performed in the context of the respective user.

#### System

```yaml
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 a few examples of how this role can be used.

1. [Basic](#basic)
Install zsh and set it as default shell for the ansible user.
2. [Multiple users](#multiple-users)
Install zsh and set it as default shell for a list of specified users.
3. [User defined config file](#user-defined-config-file)
Distribute a custom `.zshrc` file for a list of users.
4. [Custom dependencies](#custom-dependencies)
Distribute a custom `.zshrc` file with a dependency.
5. [Extra functions](#extra-functions)
Distribute a custom `.zshrc` file with `autosuggestions` and `syntax-highlighting` functions.
6. [Complete](#complete)
Full example of a zsh shell.^{[Sample Preview](#preview)}

### Basic

Install zsh and set it as default shell for the [ansible_user](https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#connection-variables).
- Install the zsh package.
- Set zsh as default shell for the `ansible_user`.

```yaml
- 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 default shell for a list of specified users.
- Install the zsh package.
- Set zsh as default shell for the specified users.

```yaml
- 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

Distribute a custom `.zshrc` file for a list of users.
- Install the zsh package.
- Set zsh as default shell for the specified users.
- Distribute a custom `.zshrc` for each user.

```yaml
- 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 distributed."
```

`zshrc.j2` file in your **templates folder**:

```jinja
{% if zsh_config_overwrite is true %}
#
# {{ ansible_managed }}
#
{% endif %}

# Add your content here.

```

### Custom dependencies

Distribute a custom `.zshrc` file with a dependency.
- Install the zsh package.
- Set zsh as default shell for the specified users.
- Distribute a custom `.zshrc` for each user.
- Install a dependency.

```yaml
- 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."
```

`zshrc.j2` file in your **templates folder**:

```jinja
{% if zsh_config_overwrite is true %}
#
# {{ 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](https://the.exa.website/) is an improved file lister with more features and better defaults. It uses colours to distinguish file types and metadata.

### Extra functions

Distribute a custom `.zshrc` file with [autosuggestions](https://github.com/zsh-users/zsh-autosuggestions#zsh-autosuggestions) and [syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting#zsh-syntax-highlighting-) functions.
- Install the zsh package.
- Set zsh as default shell for the specified users.
- Distribute a custom `.zshrc` for each user.
- Install [autosuggestions](https://github.com/zsh-users/zsh-autosuggestions#zsh-autosuggestions) and [syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting#zsh-syntax-highlighting-).

```yaml
- 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."
```

`zshrc.j2` file in your **templates folder**:

```jinja
{% if zsh_config_overwrite is true %}
#
# {{ 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 example of a zsh shell.
- Install the zsh package.
- Set zsh as default shell for the specified users.
- Distribute a custom `.zshrc` for each user.
- Install [autosuggestions](https://github.com/zsh-users/zsh-autosuggestions#zsh-autosuggestions), [syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting#zsh-syntax-highlighting-) and [exa](https://github.com/ogham/exa).
- Set `history`, `color` and `cd` settings.

```yaml
- 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."
```

`zshrc.j2` file in your **templates folder**:

Click here to see the content

```jinja
{% if zsh_config_overwrite is true %}
#
# {{ 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

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

A preview of this configuration:
![zsh console](https://raw.githubusercontent.com/patbec/zsh-console-icons/master/zsh-console.svg)
_{You can find the used [ANSI console colors here](https://github.com/patbec/zsh-console-icons#colors).}

## Licence

This project is licensed under MIT - See the [LICENSE](LICENSE) file for more information.

---

↑ [Back to top](#ansible-role-zsh)