# setup-macos-developer

Seu Mac de engenharia como código: Homebrew, dotfiles e defaults, reproduzíveis em Bash

- URL: https://fernando.moretes.com/open-source/setup-macos-developer

- Markdown: https://fernando.moretes.com/open-source/setup-macos-developer/guide.md?lang=pt

- GitHub: https://github.com/fernandofatech/dot-setup-macos-developer

- Homepage: https://fernando.moretes.com

- Language: Shell

- Topics: automation, bash, developer-setup, developer-tools, dotfiles, homebrew, macos, moretes, portfolio, productivity

- Stars: 4

- Forks: 0

- Updated: 2026-09-08T20:45:30Z

---

Scripts em Bash que transformam um Mac recém-formatado numa estação de engenharia previsível — Homebrew, dotfiles e ajustes do macOS aplicados na mesma ordem, quantas vezes for preciso.

## Por que existe

Depois de anos trocando de máquina — laptop pessoal, laptop de cliente, Mac Mini de laboratório — a conta que eu pagava não era o dia perdido instalando ferramentas. Era a semana seguinte: descobrir que o `git` tinha um alias diferente, que o `node` estava numa versão de dois anos atrás, que o terminal não tinha o mesmo tema e cada comando parecia estranho. Ambiente montado à mão não é lento — é irreproduzível.

Este repositório resolve isso do jeito mais simples que ainda funciona: scripts em Bash, versionados, que descrevem a estação de trabalho como código. O Homebrew instala o que é instalável por pacote; dotfiles carregam a configuração de shell, `git` e editor; o que sobra são ajustes do macOS que hoje eu faço clicando e amanhã não lembro onde ficava.

**O critério de sucesso:** rodar o mesmo comando em dois Macs e terminar com o mesmo ambiente. Não "parecido" — o mesmo. Se uma máquina diverge, a correção entra no repositório, não no histórico do terminal de uma máquina só.

Não é framework de dotfiles. Existem vários, alguns excelentes, e todos cobram um custo de aprendizado que não quis pagar por algo que rodo poucas vezes por ano. Bash puro é o que qualquer engenheiro lê em cinco minutos.

## O que ele cobre

- Bootstrap do Homebrew e instalação de pacotes e apps a partir de uma lista versionada — a lista é a documentação.
- Dotfiles (`~/.zshrc`, `~/.gitconfig` e afins) ligados por symlink, para que editar no repositório seja editar na máquina.
- Bash sem dependência além do que o macOS já traz — roda num Mac zerado.
- Pensado para reexecução: rodar de novo não deve quebrar o que já está pronto.
- Lint, CI, varredura de segurança e release herdados do `fernandofatech/platform`.

## Fluxo de uma execução

O script principal orquestra três frentes na mesma ordem toda vez: pacotes, dotfiles, ajustes do sistema.

### 💻 Repositório — scripts em Bash

- Script de bootstrap ordena os passos (compute)
- Lista de pacotes formulae + casks (data)
- Dotfiles zsh, git, editor (data)
- Ajustes do macOS `defaults write` (compute)

### 🍺 Homebrew — gerenciador de pacotes

- Homebrew /opt/homebrew ou /usr/local (external)

### 🖥 macOS — estado da máquina

- $HOME symlinks para os dotfiles (storage)
- Preferências do sistema Finder, teclado, Dock (storage)

### Fluxos

- user -> bootstrap: clona e executa
- bootstrap -> brew: instala se ausente
- bootstrap -> pkglist: lê
- pkglist -> brew: instala em lote
- bootstrap -> dotfiles: liga
- dotfiles -> home: symlink
- bootstrap -> defaults: opcional
- defaults -> system: aplica

## Como funciona

A ordem importa e é a mesma em toda execução. Primeiro o script confere se o Homebrew existe e instala se não — sem ele nada mais roda, então é o passo zero. Depois vem a lista de pacotes: formulae de linha de comando e casks de aplicativos, que o Homebrew processa em bloco. Só então os dotfiles são ligados ao `$HOME` por symlink, porque vários deles referenciam binários que acabaram de ser instalados. Por último, os ajustes do macOS que valem a pena automatizar: os que eu esqueço, e os que mudam comportamento de teclado e Finder.

**Idempotência:** o script foi escrito para ser reexecutado. Pacote já instalado é pulado, symlink existente não é recriado, e o Homebrew sabe ignorar o que já está na versão certa. É isso que permite usar o mesmo repositório para *manter* a máquina, não só para montar.

**Bash de propósito:** não há Python, Ansible nem Nix. Num Mac recém-formatado o que existe é `zsh`, `bash` e `curl` — tudo aqui roda com isso. O preço é menos abstração; o ganho é que qualquer pessoa abre o script e entende o que ele vai fazer com a máquina antes de rodar. Num script que pede a senha do administrador, isso não é detalhe.

Como o README é curto, a fonte de verdade sobre nomes de arquivo e flags é o próprio repositório. Leia o script principal antes da primeira execução; ele é o manual.

## Instalar e usar

1. **Clone o repositório** — `git clone https://github.com/fernandofatech/dot-setup-macos-developer.git ~/dot-setup-macos-developer`. Num Mac novo o `git` vem com as Command Line Tools; o macOS oferece instalá-las na primeira chamada.

2. **Leia antes de rodar** — Abra o script principal e a lista de pacotes. Remova o que você não usa — o objetivo é a sua máquina, não a minha. Cinco minutos aqui evitam uma hora desinstalando.

3. **Execute o bootstrap** — Rode o script principal a partir da raiz do repositório. Ele vai pedir a senha do administrador para instalar o Homebrew e para os ajustes do sistema.

4. **Recarregue o shell** — `exec zsh` ou abra um terminal novo para os dotfiles entrarem em vigor. Confira com `brew --version` e `git config --list`.

5. **Reexecute quando algo mudar** — Adicione um pacote à lista, faça commit e rode o script de novo. O que já existe é pulado; só o delta é instalado.

_Quickstart num Mac zerado — confira o nome do script principal no repositório antes de executar._

```bash
# 1. Clone
git clone https://github.com/fernandofatech/dot-setup-macos-developer.git ~/dot-setup-macos-developer
cd ~/dot-setup-macos-developer

# 2. Read what is about to run (the script is the manual)
ls -la
less ./*.sh

# 3. Run the bootstrap (asks for the admin password)
bash ./setup.sh   # replace with the main script's actual name

# 4. Reload the shell
exec zsh

# 5. Verify
brew --version && brew list | head
git config --list | head
```

> **Este script muda a máquina:** Ajustes via `defaults write` alteram preferências do sistema e alguns só voltam à mão. Num Mac gerido por MDM corporativo, confira com o time de TI antes: um perfil de configuração pode sobrescrever ou bloquear o que o script faz, e a falha é silenciosa — o comando passa e a preferência não muda.

## Convenções e esteira

O repositório segue as regras do `fernandofatech/platform`, o mesmo lugar que governa meus outros projetos públicos. Branch com prefixo de tipo — `feat/`, `fix/`, `chore/`, `docs/` — e commits em Conventional Commits. A versão sai dos commits; ninguém escreve número de versão à mão, e isso vale até para um repositório de scripts.

**Por que tanta esteira para dotfiles:** porque o custo não é o de escrever o script — é o de mantê-lo por anos sem que apodreça. O `pr-lint` recusa PR com título fora do padrão; o CI roda lint de shell; a varredura de segurança pega segredo colado por engano num `.zshrc` — e dotfile é exatamente onde token de API vai parar "só por hoje". O release automático marca cada mudança relevante, então dá para saber qual versão do setup montou qual máquina.

Corrigir a régua é mudar um arquivo no `platform`, não aqui. Esse é o ganho de centralizar: um repositório pequeno de scripts ganha a mesma disciplina de um serviço, sem carregar o YAML.

Se você for forkar, pode ignorar tudo isso: os scripts não dependem da esteira. Ela existe para o mantenedor, não para quem executa.

## Perguntas frequentes

### Funciona em Apple Silicon e Intel?

O Homebrew cuida da diferença — `/opt/homebrew` no Apple Silicon, `/usr/local` no Intel. Confira com `brew --prefix` que o shell está apontando para o caminho certo. Casks que só existem para uma arquitetura se resolvem na lista de pacotes, não no script.

### Posso usar só os dotfiles, sem instalar pacotes?

Pode; o passo de symlink é independente da instalação. Mas alguns dotfiles referenciam binários que a lista instala, então espere avisos no shell até completar o restante.

### Como manter minha versão sem perder as atualizações?

Fork, mantenha seus pacotes e dotfiles na sua branch e faça rebase de tempos em tempos. A separação entre script (mecanismo) e lista (conteúdo) existe para que o merge conflite pouco.

## Referências

- [fernandofatech/dot-setup-macos-developer](https://github.com/fernandofatech/dot-setup-macos-developer)
- [fernando.moretes.com](https://fernando.moretes.com)
- [fernandofatech/platform — workflows reutilizáveis](https://github.com/fernandofatech/platform)
- [Homebrew](https://brew.sh)
- [Conventional Commits](https://www.conventionalcommits.org)

## Quando usar

Use quando você troca de Mac com alguma frequência, quando mantém mais de uma máquina e quer as duas iguais, ou quando entra num time e precisa do ambiente de pé no primeiro dia sem depender de um wiki desatualizado. Não use se quer um framework com plugins e temas — aqui é Bash e uma lista, de propósito. E leia o script antes de rodar: um setup que pede senha de administrador merece cinco minutos de leitura.

## Links

- [GitHub repository](https://github.com/fernandofatech/dot-setup-macos-developer)
- [Homepage](https://fernando.moretes.com)