explaingit

geerlingguy/mac-dev-playbook

★ 6,965ShellAudience · developerComplexity · 3/5Setup · moderate

TLDR

An Ansible automation playbook that installs and configures a full developer Mac setup in one command, covering apps, CLI tools, and system preferences, designed to be forked and customized for your own workflow.

Mindmap

mindmap
  root((repo))
    What it does
      Automate Mac setup
      Install dev tools
      Apply system prefs
    Tech Stack
      Ansible playbook
      Shell scripts
      macOS
    What Gets Installed
      CLI tools
      Desktop apps
      Dotfiles config
    Use Cases
      New Mac setup
      Remote Mac setup
      Repeatable config
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Set up a brand new Mac with all your developer tools and apps automatically by running a single command.

USE CASE 2

Fork the playbook and customize it to create your own repeatable Mac setup you can reuse after every reinstall.

USE CASE 3

Provision a remote macOS machine over SSH with a consistent developer environment without sitting at the machine.

USE CASE 4

Keep your Mac tools and settings versioned in git so you can track what changed over time.

Tech stack

AnsibleShellPythonmacOS

Getting it running

Difficulty · moderate Time to first run · 30min

Requires installing Ansible before running, defaults are the author's personal config and need customization to match your own preferences.

License not specified in the explanation.

In plain English

This repository contains an automated Mac setup script that installs and configures a developer's tools and applications in one pass. The author, a web and software developer, uses it to get a new or wiped Mac ready for work without manually installing and tweaking dozens of programs one by one. The automation is built on Ansible, a tool that lets you describe what software and settings a computer should have, then applies those descriptions to reach that state. You run a handful of commands to get Ansible set up, then a single command runs the playbook and handles the rest. It installs command-line tools, desktop applications, programming language runtimes, and system preferences. The default setup includes common developer applications like Docker, Slack, Google Chrome, Firefox, and Sublime Text, along with a long list of command-line tools such as Git, Go, Node, PHP, and various networking utilities. It also applies the author's personal configuration files, known as dotfiles, and configures macOS system settings. All of these defaults can be overridden: you create a personal configuration file and list only the packages and apps you want, without modifying the main playbook. The playbook can also be pointed at a remote Mac over SSH, not just the machine you are sitting at. That makes it usable for setting up a cloud-hosted Mac or another machine on your network. The repository is one person's personal setup, shared publicly so others can fork it and adapt it to their own needs. The README includes a detailed from-scratch setup guide for those who want a complete reference. The project is tested automatically on GitHub Actions using real macOS infrastructure, so changes can be verified without wiping a physical machine.

Copy-paste prompts

Prompt 1
Help me fork geerlingguy/mac-dev-playbook and change the defaults to install VS Code, iTerm2, Python, and Node.js instead of the author's preferred apps.
Prompt 2
I want to add my own dotfiles to the mac-dev-playbook setup. Show me how to point the playbook at my dotfiles repository.
Prompt 3
Walk me through running geerlingguy/mac-dev-playbook on a fresh Mac from scratch, including installing Ansible before the playbook runs.
Prompt 4
How do I add a new Homebrew cask like Figma to the mac-dev-playbook and verify it with GitHub Actions before running it on my machine?
Prompt 5
I want to use mac-dev-playbook to provision a remote Mac mini over SSH. What configuration changes do I need to make?
Open on GitHub → Explain another repo

← geerlingguy on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.