wayofdev.dock

Panoramica Versioni Approfondimenti

<br>

<div align="center">
<img width="456" src="https://raw.githubusercontent.com/wayofdev/ansible-role-dock/master/assets/logo.gh-light-mode-only.png#gh-light-mode-only">
<img width="456" src="https://raw.githubusercontent.com/wayofdev/ansible-role-dock/master/assets/logo.gh-dark-mode-only.png#gh-dark-mode-only">
</div>

<br>

<br>

<div align="center">
<a href="https://actions-badge.atrox.dev/wayofdev/ansible-role-dock/goto"><img alt="Build Status" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fwayofdev%2Fansible-role-dock%2Fbadge&style=flat-square"/></a>
<a href="https://galaxy.ansible.com/wayofdev/dock"><img alt="Ansible Role" src="https://img.shields.io/ansible/role/59499?style=flat-square"/></a>
<a href="https://github.com/wayofdev/ansible-role-dock/tags"><img src="https://img.shields.io/github/v/tag/wayofdev/ansible-role-dock?sort=semver&style=flat-square" alt="Latest Version"></a>
<a href="https://galaxy.ansible.com/wayofdev/dock"><img alt="Ansible Quality Score" src="https://img.shields.io/ansible/quality/59499?style=flat-square"/></a>
<a href="https://galaxy.ansible.com/wayofdev/dock"><img alt="Ansible Role" src="https://img.shields.io/ansible/role/d/59499?style=flat-square"/></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/wayofdev/ansible-role-dock.svg?style=flat-square&color=blue" alt="Software License"/></a>
<a href="#"><img alt="Commits since latest release" src="https://img.shields.io/github/commits-since/wayofdev/ansible-role-dock/latest?style=flat-square"></a>
</div>

<br>

# Ansible Role: macOS Dock Automation

This role helps you automate the management of the macOS Dock using [dockutil](https://github.com/kcrawford/dockutil), a command-line tool that allows you to add, remove, and rearrange Dock items.

If you enjoy using this role, please consider giving it a star. Thank you!

<br>

## 🗂 Table of Contents

* [Benefits of this Role](#-benefits-of-this-role)
* [Requirements](#-requirements)
* [Role Variables](#-role-variables)
  * [Structure](#-structure)
  * [Adding](#-adding)
  * [Adding with Replace](#-adding-with-replace)
  * [Adding Folders](#-adding-folders)
  * [Removing](#-removing)
  * [Moving](#-moving)
* [Example Playbook](#-example-playbook)
* [Development](#-development)
* [Testing](#-testing)
  * [On Localhost](#-on-localhost)
  * [Over SSH](#-over-ssh)
* [Dependencies](#-dependencies)
* [Compatibility](#-compatibility)
* [License](#-license)
* [Author Information](#-author-information)
* [Credits and Resources](#-credits-and-resources)
* [Contributors](#-contributors)
* [Sponsors](#-sponsors)

<br>

## ⭐️ Benefits of this Role:

* Supports the latest version (3.x) of [dockutil](https://github.com/kcrawford/dockutil)
* Allows you to add, position, and remove items in a single command
* Compatible with the newest macOS Monterey
* Can clear all Dock items with one setting
* Handles Dock restarts automatically without needing `sudo`
* Supports all options provided by `dockutil`, like:
`--add, --remove, --move, --replacing, --position, --after, --before, --section, --allhomes, --sort, --display, --view`

<br>

## 📑 Requirements

  - **Homebrew**: You need to have `homebrew` installed (you can use `wayofdev.homebrew` to install it on macOS).
  - An up-to-date version of Ansible. During development, the roles will use new Ansible features when available (and the minimum version in `meta/main.yml` will be updated).
  - A compatible operating system. Refer to the [compatibility](#-compatibility) table.
  - The role depends on other third-party roles for various operating systems. Check `requirements.yml` and the [dependencies](#-dependencies) section.

<br>

## 🔧 Role Variables

This section explains the different ways to add, move, replace, or remove applications, spacers, and folders. Available variables and example values can be found in `defaults/main.yml`.

<br>

### → Structure

Controls the installation of `dockutil` and allows you to select a custom tap:

```yaml
# Should we try to install dockutil?
dock_dockutil_install: <true | false> # (default: true) Install dockutil using homebrew.

# Path to custom or official tap of dockutil
dock_dockutil_tap: lotyp/formulae/dockutil # Default is 3.x tap

You can completely wipe the macOS Dock:

# Removes all contents from Dock including "others" section with Downloads folder.
dock_dockitems_erase_all: <true | false> # Whether to try erasing all items in Dock. (default: false)

Variable structure for adding, moving, or removing Dock items:

dock_dockitems:
  - label: <label> # Used for searching existing items or naming new apps
    action: <add | remove | move>
    path: <label | app bundle id | path | url> # Example: /System/Applications/TextEdit.app
    replacing: <label | app bundle id | path | url> # Label or app bundle id of item to replace
    position: <[+/-]index_number | beginning | end | middle> # Fixed position for inserting the item
    after: <label | application bundle id> # Inserts the item after the given dock label
    before: <label | application bundle id> # Inserts the item before the given dock label
    section: <apps | others> # Specifies whether to add the item to the apps or others section
    display: <folder | stack> # Folder display option when adding a folder
    sort: <name | dateadded | datemodified | datecreated | kind> # Folder sort option when adding a folder
    type: <spacer | small-spacer | flex-spacer> # Custom tile type for adding spacers
    allhomes: <true | false> # Whether to locate all home directories and perform the operation on each of them (default: false)

→ Adding

Adds TextEdit.app to the end of the current user's Dock:

dock_dockitems:
  - label: TextEdit
    action: add
    path: /System/Applications/TextEdit.app

Adds Time Machine.app in the middle of the Dock:

dock_dockitems:
  - label: Time Machine
    action: add
    path: /System/Applications/Time Machine.app
    position: middle

Adds TextEdit.app after the item Time Machine.app in every user's Dock:

dock_dockitems:
  - label: TextEdit
    action: add
    path: /System/Applications/TextEdit.app
    after: Time Machine
    allhomes: true # optional

→ Adding with Replace

Replaces Time Machine.app with Mail.app in the current user's Dock:

dock_dockitems:
  - label: Mail
    action: add
    path: /System/Applications/Mail.app
    replacing: Time Machine

→ Adding Folders

Adds the Downloads folder to the others section of the Dock. Clicking it will open a preview in grid mode.

dock_dockitems:
  - label: Downloads
    action: add
    path: ~/Downloads
    view: grid
    display: folder
    allhomes: true # optional

→ Removing

Removes TextEdit from every user's Dock:

dock_dockitems:
  - label: TextEdit
    action: remove
    allhomes: true # optional

Removes all spacer tiles:

dock_dockitems:
  - label: spacer-tiles
    action: remove

→ Moving

Moves System Preferences to the second slot on every user's dock:

dock_dockitems:
  - label: System Preferences
    action: move
    position: end # <[+/-]index_number | beginning | end | middle>
    allhomes: true # optional

📗 Example Playbook

---
- hosts: all

  # Required when running over SSH
  environment:
    - PATH: "/usr/local/bin:/usr/local/sbin:/opt/homebrew/bin:{{ ansible_env.PATH }}"

  vars:
    dock_dockitems_erase_all: true
    dock_dockitems:
      - label: Messages
        action: add
        path: /System/Applications/Messages.app

      - label: Safari
        action: add
        path: /Applications/Safari.app

      - label: Sublime Text
        action: add
        path: /Applications/Sublime Text.app
        position: 3

  roles:
    - wayofdev.homebrew
    - wayofdev.dock

⚙️ Development

To install dependencies and start development, check the contents of our Makefile.

Install poetry and all development Python dependencies:

$ make install

Install only Python dependencies if you already have Poetry:

$ make install-deps

Install all git hooks:

$ make hooks

Lint all role files:

$ make lint

🧪 Testing

Check Makefile for a full list of commands for remote and local testing. For local testing, you can use the following commands:

→ On Localhost

:warning: Notice: By default, all tests run on your local machine!

# Run molecule tests on localhost
$ poetry run molecule test --scenario-name defaults-restored-on-localhost -- -vvv

# Or using make command
$ make m-local

# Choose which tags will be included
$ export TASK_TAGS="dock-validate,dock-install"; make m-local

→ Over SSH

# Run molecule scenarios against remote machines over SSH
# This requires VM setup and configuration
$ poetry run molecule test --scenario-name defaults-restored-over-ssh -- -vvv

$ make m-remote

# Tags can also be passed
$ export TASK_TAGS="dock-validate,dock-install"
$ make m-remote