# setup-macos-developer

Setup de Mac para desenvolvimento em Shell: o mesmo ambiente, em toda máquina nova

- 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-29T16:37:10Z

---

O dot-setup-macos-developer é um repositório em Shell que automatiza a configuração de uma estação de desenvolvimento macOS, para que uma máquina nova chegue ao mesmo estado da anterior sem depender de memória nem de checklist em papel.

## Por que este repositório existe

A pergunta que me fez criar este repositório não foi "como instalo minhas ferramentas?", foi "quanto tempo eu perco, e o que eu esqueço, toda vez que troco de Mac?".

Configurar uma máquina de desenvolvimento à mão parece barato porque acontece raramente. O custo aparece depois: o `git` sem a configuração de assinatura, o shell sem o alias que você usa vinte vezes por dia, a versão de runtime diferente da que o CI usa. Cada diferença dessas vira uma tarde de investigação de "na minha máquina funciona".

O custo que importa aqui não é o de instalar uma vez, é o de manter dois ou três ambientes coerentes ao longo de anos. Um script versionado resolve isso de um jeito simples: o estado desejado da máquina vira código, com histórico no Git, revisão por PR e a mesma régua de qualidade de qualquer outro repositório meu.

O escopo é deliberadamente estreito: macOS, Homebrew como gerenciador de pacotes e Bash como linguagem. Não é um framework de dotfiles genérico nem uma ferramenta de gestão de frota. É o setup da minha estação, publicado porque o padrão é reaproveitável.

## O que você encontra aqui

- **Shell puro:** nenhuma dependência além do que o macOS já traz e do Homebrew que o próprio setup instala.
- **Homebrew como fonte dos pacotes:** ferramentas de linha de comando e aplicativos saem do mesmo gerenciador, o que deixa a lista auditável.
- **Dotfiles versionados:** a configuração do ambiente fica no Git, com histórico de quem mudou o quê e por quê.
- **Convenções do `platform`:** branch `<tipo>/<escopo>`, Conventional Commits e versão derivada dos commits, sem número escrito à mão.
- **Pipeline reutilizável:** `pr-lint`, CI, segurança e release vêm dos workflows compartilhados, não de YAML copiado.

## Como o setup flui de um Mac zerado até o ambiente pronto

O repositório é a fonte do estado desejado; o script aplica esse estado na máquina local. A pipeline do platform só valida o repositório, ela não toca na sua máquina.

### 🌐 GitHub: fonte do estado

- dot-setup-macos-developer scripts + dotfiles (external)
- fernandofatech/platform workflows reutilizáveis (ci)

### 💻 macOS: aplicação local

- Script Bash entrypoint do setup (compute)
- Homebrew CLIs e apps (compute)
- Dotfiles shell, git, editor (storage)

### Fluxos

- dev -> repo: git clone
- repo -> script: código revisado
- dev -> script: executa
- script -> brew: instala pacotes
- script -> dotfiles: aplica configuração
- platform -> repo: lint, CI, segurança, release

## Instalar e usar

1. **Garanta as Command Line Tools**: Num Mac zerado, `git` só existe depois das Command Line Tools da Apple. Rode `xcode-select --install` e aceite o diálogo antes de clonar qualquer coisa.

2. **Clone o repositório**: Clone em um diretório que você vai manter, porque o repositório continua sendo a referência do ambiente depois do primeiro setup.

3. **Leia o script antes de executar**: Liste os arquivos e abra o entrypoint. Script de setup roda com o seu usuário e mexe no seu shell: nunca execute um que você não leu, incluindo este.

4. **Ajuste a lista ao seu caso**: A lista de pacotes e os dotfiles refletem a minha estação. Em um fork, remova o que você não usa antes de rodar: pacote instalado e esquecido também é custo de manutenção.

5. **Execute e abra um shell novo**: Rode o entrypoint e, ao final, abra um terminal novo para carregar a configuração de shell. Confira com `brew doctor` se o Homebrew ficou saudável.

_Quickstart: clonar, inspecionar e só então executar_

```bash
# 1. Ferramentas básicas da Apple (inclui git)
xcode-select --install

# 2. Clonar o repositório
git clone https://github.com/fernandofatech/dot-setup-macos-developer.git
cd dot-setup-macos-developer

# 3. Inspecionar antes de rodar
ls -la
less README.md

# 4. Executar o entrypoint do setup (confira o nome no repositório)
# bash ./<entrypoint>.sh

# 5. Validar
brew doctor
```

> **Script de setup roda com o seu usuário:** Nada aqui roda em sandbox. O script instala pacotes e reescreve arquivos de configuração no seu `$HOME`. Se você já tem dotfiles próprios, faça backup antes: arquivo sobrescrito não avisa, ele só some.

## Como funciona e como é mantido

O mecanismo é o mais simples possível, de propósito: um script Bash lê o estado desejado e o aplica na máquina, usando o Homebrew para pacotes e copiando ou ligando os dotfiles para o lugar certo. Não há agente, daemon nem servidor; o repositório não sabe quantas máquinas o usam.

O que torna isso sustentável não é o script, é a disciplina em volta dele. O repositório segue as convenções do [`fernandofatech/platform`](https://github.com/fernandofatech/platform):

- **Branch:** `<tipo>/<escopo>`, com `feat/`, `fix/`, `chore/` e `docs/`.
- **Commit e título de PR:** [Conventional Commits](https://www.conventionalcommits.org).
- **Versão:** sai dos commits. Ninguém escreve número de versão à mão.

A pipeline (`pr-lint`, CI, segurança e release) vem dos workflows reutilizáveis do `platform`. A consequência prática: corrigir a régua de qualidade é mudar um arquivo lá, não em cada repositório. Num portfólio com dezenas de repositórios, essa é a diferença entre manter uma pipeline e manter vinte cópias dela que divergem em silêncio.

Para um repositório de setup, a release versionada também tem uso concreto: dá para dizer em que versão do setup uma máquina foi configurada e o que mudou desde então.

## Limites que vale conhecer

Shell imperativo resolve bem o primeiro setup e razoavelmente bem as reexecuções, desde que cada passo confira antes de agir (pacote já instalado, arquivo já no lugar). Ele não oferece o que uma ferramenta declarativa oferece: não há plano mostrando o que vai mudar antes de mudar, e remover um pacote da lista não o desinstala da máquina.

Também não há gestão de segredo aqui, e não deve haver. Chave SSH, token de API e credencial de nuvem ficam fora do repositório, em cofre ou gerados na máquina. Um repositório público de dotfiles com segredo dentro não é um descuido pequeno, é um incidente.

Por fim, o repositório é pequeno: 4 estrelas, nenhum fork, um mantenedor. Ele é um exemplo funcional e um ponto de partida para o seu fork, não um projeto com roadmap ou suporte.

## Perguntas frequentes

### Funciona em Linux?

Não é o objetivo. O escopo é macOS com Homebrew; partes do Bash podem rodar em Linux, mas nada aqui foi pensado nem testado para isso.

### Posso rodar de novo numa máquina já configurada?

Leia o script antes. Reexecução só é segura nos passos que conferem o estado antes de agir; qualquer passo que copia arquivo por cima do existente vai sobrescrever o que você mudou à mão.

### Devo usar direto ou fazer fork?

Faça fork. A lista de pacotes e os dotfiles são os meus. O valor reaproveitável está na estrutura e no processo, não na minha escolha de ferramentas.

## Referências

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

## Para quem é

Use este repositório como base quando você troca de Mac mais de uma vez por ano, trabalha sozinho ou num time pequeno, e quer o ambiente versionado com a mesma disciplina de PR e release do resto do seu código. Prefira uma ferramenta declarativa (Nix, Ansible ou o MDM da empresa) quando você precisa garantir o estado de uma frota, desfazer mudanças de forma confiável ou provar conformidade para auditoria. Shell resolve bem o problema de uma pessoa; não resolve o problema de cinquenta máquinas.

## Links

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