# atomantic/dotfiles: a macOS machine setup script that backs up before it overwrites

> atomantic/dotfiles is an interactive, idempotent installer that symlinks shell and editor config into $HOME, applies macOS defaults, and installs software by category. The interesting part is not the dotfiles themselves but the backup, restore and machine-local override design around them.

**atomantic/dotfiles** — 🖥️ Automated Configuration, Preferences and Software Installation for macOS

- Repository: https://github.com/atomantic/dotfiles
- Stars: 1,362 · Forks: 425
- Language: Shell
- License: ISC
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/atomantic-dotfiles

## The problem: a new Mac costs a day of preference archaeology

The README opens with the complaint directly: getting a new laptop or joining a new team means spending a whole day on system preferences and tools. The project's answer is to do that work once and encode it. It describes itself as having started as Adam Eivy's macOS shell configuration but grown into "a multi-developer platform for machine configuration".

The README claims it works on a factory-new machine and on one you have used for years. That second case is the harder one, because an existing machine already has a .zshrc, a .gitconfig and a Dock you have arranged by hand. The design decision that follows from this is the first thing install.sh does: back up before replacing.

## Backup, symlink, override: how install.sh actually moves files

install.sh is the single entry point. The README describes it as interactive (it asks before each major step) and idempotent (safe to run again and again). The mechanism is a three-part flow.

First, anything it is about to replace is copied into ~/.dotfiles_backup/<timestamp>/. That timestamped directory is what restore.sh reads later, so a bad run is reversible without git.

Second, files in homedir/ are symlinked into $HOME: .zshrc, .vimrc, .gitconfig, .shellaliases, .shellfn and others. The tracked repository stays the source of truth, and edits made through the symlink show up as changes in the clone.

Third, it seeds untracked machine-local override files and then leaves them alone. The README gives the contract in a table: ~/.gitconfig.local is pulled in by an [include] line in ~/.gitconfig, ~/.gitignore.local is wired through git's core.excludesfile, and ~/.zshrc.local is sourced at the end of ~/.zshrc. The point is that private or proprietary per-machine settings never enter the repo, and git pull or ./update.sh cannot conflict with them.

That last detail is the design worth copying. Many dotfiles repositories solve the private-settings problem with stow packages or hostname conditionals. This one solves it with three named files that the installer creates once and never rewrites.

## Installing it and getting to a first usable shell

The README gives a single clone-and-run sequence. It uses --recurse-submodules because the repository carries submodules such as oh-my-zsh and stevenblack-hosts, and it clones into ~/.dotfiles. The README adds a warning in the same block: run it from Terminal, not iTerm, or iTerm settings may be discarded on exit.

```bash
git clone --recurse-submodules https://github.com/atomantic/dotfiles ~/.dotfiles
cd ~/.dotfiles;
./install.sh
```

The README is explicit that you should review the script first, and that you are responsible for what it does to your machine. It also notes the author has "a high tolerance for nuking his machine and starting over", which is a fair signal about the intended risk posture.

During the run, expect prompts rather than a silent script. The README lists what it asks about: your git identity (name, email, github username) written to ~/.gitconfig.local; an optional overwrite of /etc/hosts using StevenBlack/hosts, with your own entries going in configs/hosts.local; macOS system tweaks; and software installation per category (Homebrew CLI tools and desktop apps, npm globals, Mac App Store apps, Ruby gems). Every prompt can be declined, so a first run can apply only the parts you want.

When it finishes, the README says to open iTerm, press Command + , and under Profiles > Colors choose Load Presets, then the Solarized Dark Patch scheme. If it is missing, import it from ~/.dotfiles/configs. The README also mentions selecting the Hack font and setting the non-ascii font to Roboto Mono For Powerline. The prompt itself comes from powerlevel10k, and the README points to ./.zshrc for changing what it shows.

## Updating, restoring and the cost of keeping a fork

For an existing install, the README directs you to ./update.sh instead of install.sh. That script pulls the latest code and then runs install.sh for you. Because install.sh is idempotent, re-running it is the documented way to pick up new configuration or software, and because the override files are never touched, a pull should not collide with local edits.

Rollback is handled by restore.sh against the timestamped directory under ~/.dotfiles_backup/. The README does not document what restore.sh does when more than one backup directory exists, so if you run install.sh repeatedly you are choosing among backups yourself.

The README recommends forking the repository "in case you don't like anything I do and want to set your own preferences (and pull request them)". That is honest advice with a real cost: a fork means you own the merge. Upstream changes to homedir/ arrive as conflicts against your edits rather than as clean pulls. The machine-local override files reduce that pressure, since most personal settings belong there, but anything you change inside homedir/ reintroduces it. The README also carries a 3.x.x+ upgrade section, which tells you the project has changed its layout enough in the past to require migration instructions.

## What it does not do: Linux, and anything outside macOS

The repository description is unambiguous: automated configuration, preferences and software installation for macOS. The README's settings sections are Finder, Dock and Dashboard, hot corners, Spotlight, iTerm2, Time Machine, Activity Monitor, Dashboard/iCal/TextEdit/Disk Utility, Mac App Store, Messages and security. None of that maps to a Linux desktop, and none of it maps to a window manager such as Hyprland, which is a common target for dotfiles repositories elsewhere.

The software installation path is the same story. Homebrew, npm globals, Mac App Store apps and Ruby gems are the categories the installer prompts for. If you are on Arch, Ubuntu or KDE, this project is not a partial fit; it is the wrong tool, and the shell fragments in homedir/ are not worth extracting on their own when smaller, portable alternatives exist.

There is a second limitation closer to home. The installer changes macOS system defaults and can overwrite /etc/hosts. Those are machine-wide effects, not user-level ones. The README's liability section and its instruction to review the script are the project's own acknowledgement of that. If you cannot accept a script writing system defaults on a machine you share or depend on, decline those prompts.

## Alternatives and how their approach differs

GNU Stow takes the opposite stance on scope. It is a symlink manager: you organize packages in directories and stow them into $HOME. It does not back up what it replaces, does not apply system settings, and does not install software. If your actual problem is only "keep my config in git and link it", Stow is smaller and does not ask for sudo. The trade-off is that you write the backup and restore logic yourself, which is exactly the part atomantic/dotfiles ships.

A bare dotfiles repository with a bootstrap script sits between the two. You get full control over layout and no upstream opinions about your Dock or your /etc/hosts, but you also get no timestamped backup directory, no restore.sh, and no seeded override files. If you have already built that, this project's contribution is the override-file convention and the backup step, not the shell configuration.

Where atomantic/dotfiles is genuinely different from both is the prompt-per-category model. It is not a declarative manifest you edit and apply; it is an interview you can decline section by section. That suits a one-off machine setup and suits poorly a fleet where you want the same answer every time.

## Licence and maintenance

The repository is licensed under ISC, a permissive licence whose text is functionally close to MIT: keep the copyright notice and permission notice, and the software is provided without warranty. The README reinforces the no-warranty position in its own words, telling you that you are responsible for everything the script does to your machine. That matters more here than in a library, because the script writes system defaults and can replace /etc/hosts. ISC does not give you any indemnity for a machine you had to reinstall.

The last push to the repository was on 2026-08-27, and the repository is not archived. The most recent release listed is v7.0.0, dated 2025-09-09, described as a complete architectural overhaul with zero dependencies. Before that, 6.1.0 and 6.0.1 were released in July 2025. The gap between the v7.0.0 release and the most recent push suggests active work continues between tagged releases, but the release cadence is not something the README commits to, and there is no published support policy for older macOS versions beyond the 3.x.x+ migration section.

## Conclusion

Adopt atomantic/dotfiles if you are setting up a macOS machine and want one script that backs up what it replaces, keeps private settings out of the repo, and can be re-run without duplicating work. Do not adopt it if you run Linux or a window manager such as Hyprland: every setting category in the README is macOS-specific, and the software install steps are Homebrew, Mac App Store and Ruby gems. Before running install.sh, read it, check what lands in ~/.dotfiles_backup, and decide whether you want the /etc/hosts overwrite from StevenBlack/hosts, because that is the one step that changes a file outside your home directory.

## FAQ

### How do I install atomantic/dotfiles on a new Mac?

Clone the repository into ~/.dotfiles with submodules, then run ./install.sh from Terminal rather than iTerm. The script prompts before each major step, so you can decline anything you do not want.

### How do I use atomantic/dotfiles after installing it?

The installer symlinks files from homedir/ into $HOME and seeds ~/.gitconfig.local, ~/.gitignore.local and ~/.zshrc.local for machine-specific settings. Re-run ./update.sh to pull the latest code and apply it again.

### What is a dotfile, in the context of this repository?

It is a configuration file whose name starts with a dot, such as .zshrc, .vimrc or .gitconfig. atomantic/dotfiles keeps those files in a homedir/ directory and symlinks them into your home directory.

## Sources

- [atomantic/dotfiles on GitHub](https://github.com/atomantic/dotfiles)
- [Issues](https://github.com/atomantic/dotfiles/issues)
- [License: ISC](https://github.com/atomantic/dotfiles/blob/main/LICENSE)
- [README](https://github.com/atomantic/dotfiles/blob/main/README.md)
- [Releases](https://github.com/atomantic/dotfiles/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/atomantic-dotfiles