Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 3 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 (3 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
# 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
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
A preview of this configuration:
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)