{"id":15211107,"url":"https://github.com/patbec/ansible-role-zsh","last_synced_at":"2025-10-03T03:30:31.996Z","repository":{"id":65423415,"uuid":"481968464","full_name":"patbec/ansible-role-zsh","owner":"patbec","description":"A simple role to install and set up the zsh shell on Linux with Ansible.","archived":true,"fork":false,"pushed_at":"2023-03-26T11:54:44.000Z","size":57,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-29T08:04:48.094Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://galaxy.ansible.com/patbec/zsh","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patbec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-15T13:32:42.000Z","updated_at":"2024-01-24T14:51:26.000Z","dependencies_parsed_at":"2023-02-12T19:00:22.245Z","dependency_job_id":null,"html_url":"https://github.com/patbec/ansible-role-zsh","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbec%2Fansible-role-zsh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbec%2Fansible-role-zsh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbec%2Fansible-role-zsh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patbec%2Fansible-role-zsh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patbec","download_url":"https://codeload.github.com/patbec/ansible-role-zsh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235069298,"owners_count":18930936,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2024-09-28T08:04:48.568Z","updated_at":"2025-10-03T03:30:26.730Z","avatar_url":"https://github.com/patbec.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg align=\"right\" width=\"22%\" src=\"https://raw.githubusercontent.com/patbec/zsh-console-icons/master/zsh-console-auto.svg\" alt=\"zsh console icon\"/\u003e\n\n# Ansible Role: ZSH\n\n![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)\n\n## Deprecated: This role has been migrated to a Collection, [here you can find the new version](https://galaxy.ansible.com/bec/shell).\n\nThis is a simple role to install and set up the **zsh-shell** on Linux.\n\nThe following steps are supported:\n- Install zsh with custom packages\n- Set zsh as default shell for the specified users\n- Optional distribution of configuration files\n\nThis role is kept simple, uses the standard package manager and contains minimal overhead. If you have any problems, feel free to create an issue.\n\n## Preparation\n\nInstall this role with Ansible Galaxy.\n```shell\nansible-galaxy install patbec.zsh\n```\n\n## Variables\n\nDefault variables in this playbook.\n\n| Name                 | Description                                            | Default Value        |\n| -------------------- | ------------------------------------------------------ | -------------------- |\n| zsh_config_mode      | Default permissions for distributed files.             | `0644`               |\n| zsh_config_backup    | Creates a backup before overwriting.                   | `true`               |\n| zsh_config_overwrite | Overwrites the existing file if there are differences. | `false`              |\n| zsh_users_config     | A list of zsh files to be distributed for a user.      | `[]`                 |\n| zsh_system_config    | A list of zsh files to be distributed globally.        | `[]`                 |\n| zsh_users            | A list of users who should get zsh as default shell.   | `{{ ansible_user }}` |\n| zsh_dependencies     | A list of additional packages to install.              | `[]`                 |\n| zsh_executable       | Path to the executable.                                | `/usr/bin/zsh`       |\n\n\u003e **Molecule:** Unit test fails if a symbolic link is specified for `zsh_executable`.\n\nThe `zsh_users_config` property is a dictionary:\n\n```yaml\nzsh_users_config:\n  - template: \"zshrc.j2\"\n    filepath: \"$HOME/.zshrc\"\n```\n\nThis basic example distributes a `.zshrc` for a user. Ansible looks for the `zshrc.j2` file in your `template` folder.\n\n### Paths\n\nHere is a list of possible paths from the [zsh documentation (5.2 Files)](https://zsh.sourceforge.io/Doc/Release/Files.html#Files-1).\n\n#### Users\n\n```yaml\nzsh_users_config:\n  - template: \"zshrc.j2\"\n    filepath: \"$HOME/.zshrc\"\n  - template: \"zshenv.j2\"\n    filepath: \"$HOME/.zshenv\"\n  - template: \"zprofile.j2\"\n    filepath: \"$HOME/.zprofile\"\n  - template: \"zlogin.j2\"\n    filepath: \"$HOME/.zlogin\"\n  - template: \"zlogout.j2\"\n    filepath: \"$HOME/.zlogout\"\n```\n\n\u003ci\u003eThe copy operation is performed in the context of the respective user.\u003c/i\u003e\n\n#### System\n\n```yaml\nzsh_system_config:\n  - template: \"zshrc.j2\"\n    filepath: \"/etc/zshrc\"\n  - template: \"zshenv.j2\"\n    filepath: \"/etc/zshenv\"\n  - template: \"zprofile.j2\"\n    filepath: \"/etc/zprofile\"\n  - template: \"zlogin.j2\"\n    filepath: \"/etc/zlogin\"\n  - template: \"zlogout.j2\"\n    filepath: \"/etc/zlogout\"\n```\n\n## Examples\n\nHere are a few examples of how this role can be used.\n\n  1. [Basic](#basic)\u003cbr\u003eInstall zsh and set it as default shell for the ansible user.\n  2. [Multiple users](#multiple-users)\u003cbr\u003eInstall zsh and set it as default shell for a list of specified users.\n  3. [User defined config file](#user-defined-config-file)\u003cbr\u003eDistribute a custom `.zshrc` file for a list of users.\n  4. [Custom dependencies](#custom-dependencies)\u003cbr\u003eDistribute a custom `.zshrc` file with a dependency.\n  5. [Extra functions](#extra-functions)\u003cbr\u003eDistribute a custom `.zshrc` file with `autosuggestions` and `syntax-highlighting` functions.\n  6. [Complete](#complete)\u003cbr\u003eFull example of a zsh shell.\u003csup\u003e[Sample Preview](#preview)\u003c/sup\u003e\n\n### Basic\n\nInstall zsh and set it as default shell for the [ansible_user](https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#connection-variables).\n- Install the zsh package.\n- Set zsh as default shell for the `ansible_user`.\n\n```yaml\n- name: zsh\n  hosts: all\n  roles:\n    - patbec.zsh\n  tasks:\n    ansible.builtin.debug:\n        msg: \"ZSH has been installed and set as default for the user {{ ansible_user }}.\"\n```\n\n### Multiple users\n\nInstall zsh and set it as default shell for a list of specified users.\n- Install the zsh package.\n- Set zsh as default shell for the specified users.\n\n```yaml\n- name: zsh\n  hosts: all\n  vars:\n    zsh_users:\n      - lorem\n      - ipsum\n  roles:\n    - patbec.zsh\n  tasks:\n    ansible.builtin.debug:\n        msg: \"ZSH was installed and set as default for 2 users.\"\n```\n\n### User defined config file\n\nDistribute a custom `.zshrc` file for a list of users.\n- Install the zsh package.\n- Set zsh as default shell for the specified users.\n- Distribute a custom `.zshrc` for each user.\n\n```yaml\n- name: zsh\n  hosts: all\n  vars:\n    zsh_config_backup: false\n    zsh_config_overwrite: true\n\n    zsh_users:\n      - lorem\n      - ipsum\n\n    zsh_users_config:\n      - template: \"zshrc.j2\"\n        filepath: \"$HOME/.zshrc\"\n\n  roles:\n    - patbec.zsh\n  tasks:\n    ansible.builtin.debug:\n        msg: \"ZSH was installed and a custom file was distributed.\"\n```\n\n`zshrc.j2` file in your **templates folder**:\n\n```jinja\n{% if zsh_config_overwrite is true %}\n#\n# {{ ansible_managed }}\n#\n{% endif %}\n\n# Add your content here.\n\n```\n\n### Custom dependencies\n\nDistribute a custom `.zshrc` file with a dependency.\n- Install the zsh package.\n- Set zsh as default shell for the specified users.\n- Distribute a custom `.zshrc` for each user.\n- Install a dependency.\n\n```yaml\n- name: zsh\n  hosts: all\n  vars:\n    zsh_config_backup: false\n    zsh_config_overwrite: true\n\n    zsh_users:\n      - lorem\n      - ipsum\n\n    zsh_users_config:\n      - template: \"zshrc.j2\"\n        filepath: \"$HOME/.zshrc\"\n\n    zsh_dependencies:\n      - exa\n  roles:\n    - patbec.zsh\n  tasks:\n    ansible.builtin.debug:\n        msg: \"ZSH has been installed and exa is used to list files.\"\n```\n\n`zshrc.j2` file in your **templates folder**:\n\n```jinja\n{% if zsh_config_overwrite is true %}\n#\n# {{ ansible_managed }}\n#\n{% endif %}\n\nalias ls='exa --group-directories-first'\nalias ll='exa --group-directories-first --all --long --binary --group --classify --grid'\nalias la='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale'\nalias lx='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale --extended'\n```\n\n\u003e [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.\n\n### Extra functions\n\nDistribute 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.\n- Install the zsh package.\n- Set zsh as default shell for the specified users.\n- Distribute a custom `.zshrc` for each user.\n- 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-).\n\n```yaml\n- name: zsh\n  hosts: all\n  vars:\n    zsh_config_backup: false\n    zsh_config_overwrite: true\n\n    zsh_users:\n      - lorem\n      - ipsum\n\n    zsh_users_config:\n      - template: \"zshrc.j2\"\n        filepath: \"$HOME/.zshrc\"\n\n    zsh_dependencies:\n      - zsh-autosuggestions\n      - zsh-syntax-highlighting\n  roles:\n    - patbec.zsh\n  tasks:\n    ansible.builtin.debug:\n        msg: \"ZSH was installed and additional functions were enabled.\"\n```\n\n`zshrc.j2` file in your **templates folder**:\n\n```jinja\n{% if zsh_config_overwrite is true %}\n#\n# {{ ansible_managed }}\n#\n{% endif %}\n\nautoload colors \u0026\u0026 colors\n\nsource  /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh\nsource  /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh\n```\n\n### Complete\n\nFull example of a zsh shell.\n- Install the zsh package.\n- Set zsh as default shell for the specified users.\n- Distribute a custom `.zshrc` for each user.\n- 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).\n- Set `history`, `color` and `cd` settings.\n\n```yaml\n- name: zsh\n  hosts: all\n  vars:\n    zsh_config_backup: false\n    zsh_config_overwrite: true\n\n    zsh_users:\n      - lorem\n      - ipsum\n\n    zsh_users_config:\n      - template: \"zshrc.j2\"\n        filepath: \"$HOME/.zshrc\"\n\n    zsh_dependencies:\n      - exa\n      - zsh-autosuggestions\n      - zsh-syntax-highlighting\n\n    zsh_additional_lines: \"\"\n  roles:\n    - patbec.zsh\n  tasks:\n    ansible.builtin.debug:\n        msg: \"ZSH was installed.\"\n```\n\n`zshrc.j2` file in your **templates folder**:\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eClick here to see the content\u003c/b\u003e\u003c/summary\u003e\n\n  ```jinja\n  {% if zsh_config_overwrite is true %}\n  #\n  # {{ ansible_managed }}\n  #\n  {% endif %}\n\n  autoload colors \u0026\u0026 colors\n\n  PROMPT=\"%(?:%{$fg_bold[green]%}➜ :%{$fg_bold[red]%}➜ )\"\n  PROMPT+=\" %{$fg[cyan]%}%c%{$reset_color%} \"\n\n  source  /usr/share/zsh-autosuggestions/zsh-autosuggestions.zsh\n  source  /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh\n\n  alias ls='exa --group-directories-first'\n  alias ll='exa --group-directories-first --all --long --binary --group --classify --grid'\n  alias la='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale'\n  alias lx='exa --group-directories-first --all --long --binary --group --header --links --inode --modified --blocks --time-style=long-iso --color-scale --extended'\n\n  HISTFILE=\"$HOME/.zsh_history\"\n  HISTSIZE=50000\n  SAVEHIST=50000\n\n  setopt INC_APPEND_HISTORY\n  setopt AUTOCD\n\n  {% if zsh_additional_lines is defined %}\n  #\n  # Host specific additions\n  #\n  {{ zsh_additional_lines }}\n  {% endif %}\n  ```\n\u003c/details\u003e\n\n#### Preview\n\nA preview of this configuration:\n![zsh console](https://raw.githubusercontent.com/patbec/zsh-console-icons/master/zsh-console.svg)\n\u003csub\u003eYou can find the used [ANSI console colors here](https://github.com/patbec/zsh-console-icons#colors).\u003c/sub\u003e\n\n## Licence\n\nThis project is licensed under MIT - See the [LICENSE](LICENSE) file for more information.\n\n---\n\n\u0026uarr; [Back to top](#ansible-role-zsh)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatbec%2Fansible-role-zsh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatbec%2Fansible-role-zsh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatbec%2Fansible-role-zsh/lists"}