first commit

README.md

@@ -0,0 +1,127 @@
+# Ansible Role Oh My ZSH
+
+This is a basic Ansible role to enable and configure Oh My Zsh on Fedora,
+Ubuntu, or MacOS. It should also work on many other \*nix variants. It
+performs the following tasks:
+
+- Install and minimally configure Zsh:
+  - make sure it exists,
+  - set it as the default shell for the user specified by the role.
+- Install Oh My Zsh for each specified user (in `~/.oh-my-zsh` by default).
+- Configure (Oh My) Zsh by optionally creating a `.zshrc` file for each
+  specified user.
+- Alternately, configure Zsh by adding a block of lines to individual
+  users' `.zshrc` files.
+
+## Role variables
+
+| Variable name  | Default value | Description |
+|----------------|---------------|-------------|
+| `omz_install_zsh` | `false` | Defines whether or not the role should attempt to install Zsh. |
+| `omz_user` | `[]` | The user to install/configure (Oh My) Zsh for. See below for its properties. |
+| `omz_user.name` | `-` | The name of the user. |
+| `omz_user.group` | `-` | The group of the user |
+| `omz_user.settings` | `-` | Extra settings (as a mult-line string) such as variable exports or aliases to add to the user's `.zshrc` file. Only used if `omz_zshrc_create` is `true`. |
+| `omz_git_repository` | `https://github.com/robbyrussell/oh-my-zsh.git` | The git repo to clone Oh My Zsh from. |
+| `omz_install_directory` | `.oh-my-zsh` | The name of the directory to clone Oh My Zsh into. |
+| `omz_zshrc_create` | `true` | Whether or not to create `.zshrc`. If `true`, will create `.zshrc` from a template. |
+| `omz_zshrc_template` | `templates/zshrc.zsh-template.j2` | The template used to create the user's `.zshrc` file when `omz_zshrc_create` is `true`. |
+| `omz_zshrc_backup` | `true` | Whether or not to create backup the existing `.zshrc` files when the role changes it. |
+| `omz_zsh_theme` | `robbyrussell` | See `templates/zshrc.zsh-template`. |
+| `omz_case_sensitive` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_hyphen_insensitive` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_disable_auto_update` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_update_zsh_days` | `13` | See `templates/zshrc.zsh-template`. |
+| `omz_disable_ls_colors` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_disable_auto_title` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_enable_correction` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_completion_waiting_dots` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_disable_untracked_files_dirty` | `false` | See `templates/zshrc.zsh-template`. |
+| `omz_hist_stamps` | `mm/dd/yyyy` | See `templates/zshrc.zsh-template`. |
+| `omz_zsh_custom` | `$ZSH/custom` | See `templates/zshrc.zsh-template`. |
+| `omz_plugins` | `[]` | A list of Oh My Zsh plugins to enable. |
+
+## Role task files
+
+### `main.yml`: task coordination
+
+This file includes files that peform specific subsets of tasks.
+
+### `zsh.yml`: Zsh setup
+
+This task installs and sets zsh as the default shell for a user.
+
+#### Variables used
+
+- `omz_user`
+
+### `oh-my-zsh-install.yml`: Oh My Zsh installation
+
+This task clones the Oh My Zsh repository into the user directory of each
+specified user and sets the appropriate permissions on the directory.
+
+#### Variables used
+
+- `omz_user`
+- `omz_install_directory`
+- `omz_git_repository`
+- `omz_install_path`
+
+### `oh-my-zsh-zshrc.yml`: Oh My Zsh configuration
+
+This task creates the user a `.zshrc` file containing global values for various
+Oh My Zsh options based on [the `.zshrc` template in the oh-my-zsh repository](https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/templates/zshrc.zsh-template).
+The task can be configured to back up any existing `.zshrc` file.
+
+This task only runs when `omz_zshrc_create` is set to `true`.
+
+#### Variables used
+
+- `omz_user`
+- `omz_zshrc_template`
+- `omz_zshrc_backup`
+
+### `zsh-zshrc.yml`: final Zsh configuration
+
+This task adds individual lines to the `.zshrc` file. This is useful for adding
+Zsh settings on an already-existing `.zshrc` file without creating it
+from scratch.
+
+This task only runs when `omz_zshrc_create` is set to `false`.
+
+#### Variables used
+
+- `omz_user`
+- `omz_zshrc_backup`
+
+## Sample playbook
+
+    ---
+    - name: Playbook
+      hosts: all
+      become: true
+
+      vars:
+        omz_install_zsh: true
+        users:
+          - name: "lorem"
+            group: "lorem"
+            settings: ""
+          - name: "ipsum"
+            group: "ipsum"
+            settings: |
+              export PATH="/usr/local/sbin:$path"
+              alias l="ls -AF"
+      tasks:
+        - name: Run ansible-role-oh-my-zsh.
+          include_role:
+            name: "ansible-role-oh-my-zsh"
+          vars:
+            omz_user: "{{ item }}"
+            # Only create `.zshrc` for user 'lorem'; item.settings will be
+            # appended to `.zshrc` for the user 'ipsum'.
+            omz_zshrc_create: "{{ (item.name == 'lorem') | ternary(true, false) }}"
+            omz_plugins:
+              - "autojump"
+              - "git"
+          with_items: "{{ users }}"