# nicksp/dotfiles makes you change your DNS before it installs anything

> A personal macOS setup for Zsh and Homebrew, installed either by four scripts run in order or by one symlinking script marked use at your own risk. The first installation step is not a script at all: it is a list of Cloudflare resolver addresses for you to type into network settings.

**nicksp/dotfiles** — My personal dotfiles: Zsh, Git, VSCode, Obsidian, Ghostty, cmux, etc.

- Repository: https://github.com/nicksp/dotfiles
- Website: https://github.com/nicksp/dotfiles
- Stars: 469 · Forks: 101
- Language: Shell
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/nicksp-dotfiles

## Step one is four DNS addresses you have to type in yourself

The installation list starts before any code runs. The first item asks you to point your DNS servers at Cloudflare DNS, and it gives four addresses rather than two:

- `1.1.1.1`
- `1.0.0.1`
- `2606:4700:4700::1111`
- `2606:4700:4700::1001`

That step has no script behind it, because it happens in your network settings, and it is the one instruction in the whole file that cannot be automated from a shell. Both address families are listed, so an IPv6 connection will use the same resolvers rather than falling back.

The rest of the pre-installation work is account and tooling setup rather than configuration. You generate an SSH key, add it to the ssh-agent, add the public key to your GitHub account and test it with:

```shell
ssh -T git@github.com
```

Then you configure GPG commit signature verification, install the MonoLisa font, and choose a manual or an automatic installation. The seven numbered items are all written as ones in the source, which means the visible order comes from how the list is marked up rather than from the numbers, so a reader following along is relying on position.

The requirements are stated plainly above the list: macOS, Homebrew, and Zsh, with a note that the install script will install both Homebrew and Zsh. Nothing in the visible instructions describes a Linux path, and the repository is described as a configuration for macOS specifically.

## Four scripts in order, or one script that symlinks your home directory

The manual path is four invocations from a fresh clone:

```shell
git clone git@github.com:nicksp/dotfiles.git ~/dotfiles
cd ~/dotfiles
./setup/zsh.sh
./setup/brew.sh
./setup/misc.sh
./setup/symlinks.sh
```

The order is the content. Zsh first, then Homebrew, then a miscellaneous step, and the symlink step last, which is consistent with a setup where the shell has to exist before a package manager can install the shell's dependencies.

The automatic path collapses that into one script and carries a caution instead of instructions:

```shell
git clone git@github.com:nicksp/dotfiles.git ~/dotfiles
~/dotfiles/setup.sh
```

The behaviour is stated in one sentence: it will install all required dotfiles in your home directory as symlinks, after which everything is configured by modifying files in ~/dotfiles. That is the whole model. There is no copy step, so your home directory holds links pointing into one checkout, and a change to a file in the repository is a change in your shell immediately.

The file itself recommends forking the repository to create your own set of dotfiles, and asks that pull requests only fix bugs or add improvements without any breaking changes. Both requests follow from the symlink model: a merge that changes a config file changes the fork's shell, and a fork is what makes the checkout yours to edit. The phrase attached to the one-line install, Use at your own risk, is about the same thing.

## Updating reroutes manual installers onto the script they avoided

The update section is three lines and uses the automated installer regardless of which path you chose:

```shell
cd ~/dotfiles
git pull
./setup.sh
```

A manual installer reading that has to either switch to the script or work out on their own that the four setup scripts should be re-run in the same order. Nothing in the updating section repeats the manual sequence, and nothing says the two are equivalent, so the manual path quietly converges on the automated one the first time you update.

That is not a bug so much as an unfinished distinction, but it has a practical cost for anyone who picked the manual path precisely because they wanted to run steps individually. Their first update runs a script that creates symlinks across the home directory, which is the step they declined to run.

The three extras after the main install follow the same pattern of one command per operation: `set-defaults` applies the macOS defaults kept in a shell script under setup, `sync-color-themes` installs the color scheme, and alternative application icons are handled by a separate script documented in its own readme under the icons directory. Each of these is a small, reversible operation, and each is named in a way that makes it safe to run individually.

## Three local files, and one of them is meant for credentials

The escape hatch for anything machine-specific is three files in your home directory that the configuration picks up if they exist.

`~/.zsh.local` is sourced automatically after all the other shell related files, so its contents can add to or overwrite existing aliases, settings and PATH entries. `~/.ssh/config.local` is included after the public SSH hosts, which lets you add hosts without editing the shared list. `~/.gitconfig.local` is included after the configurations from `~/.gitconfig`, so it can overwrite or add to the git configuration in the same way.

That last one carries an explicit recommendation: use `~/.gitconfig.local` to store sensitive information such as the git user credentials for individual repositories. Read that as what it is. Credentials for one repository, living in a file inside your home directory that the dotfiles repository does not manage, is the standard arrangement for per repository identity settings, and putting anything with a secret in it in a file you might later add to version control would be a mistake.

The ordering guarantee is what makes the pattern usable. Each file is included after its managed counterpart rather than instead of it, so a local file can override a managed setting without deleting the line it overrides, which means the repository version of the setting survives and the local one wins predictably.

## A private npm package whose only dependency encodes images

The repository carries a package manifest, and it is not incidental tooling. The package is named dotfiles at version 0.0.1, marked private, and pinned to pnpm 11.1.3 as its package manager with Node 24 or later required.

Its dependency list has exactly one entry:

```json
"dependencies": {
  "avif": "^0.5.3"
}
```

A dotfile repository does not need a runtime library for anything a shell does, so an image encoder in the dependency position is a signal about what this checkout is used for beyond configuration: there is a screenshot at the root, an icons directory with documented variants, and a fonts directory, and converting or producing AVIF is a plausible job for a script in the tree.

The development side is more conventional. Prettier at 3.8.3 with prettier-plugin-sh at 0.18.1 formats the shell files alongside the JavaScript, TypeScript, Markdown and JSON, and the format script passes an ignore unknown flag plus the bin directory so that files without an inferable type do not stop the run. The check script points at a path inside the bin tree:

```json
"scripts": {
  "check": "bin/lib/check",
  "format": "prettier --log-level warn --ignore-unknown --write \"**/*.{js,cjs,ts,md,json,sh}\" \"bin/*\""
}
```

So bin/ holds both the hand written command line scripts the feature list advertises and a lib directory holding a checker. A private package at 0.0.1 is never published, which is the right arrangement for this and means the manifest exists only to pin tools for whoever works in the checkout.

## More applications are configured than the feature list mentions

The feature list names a color scheme under a colors directory, command line scripts under bin, coding agent configuration automation under agents, a Starship based zsh theme with git status, git aliases, zsh aliases, fzf integration, Obsidian as a second brain, macOS defaults, VS Code settings, Firefox custom styles and a Brewfile of applications and extensions.

The top level of the repository is longer than that. Alongside the directories the list covers, it holds directories for Dash, LazyGit, Lazydocker, Nimble Commander, Rectangle, QuickLook plugins, syntax highlighting, icons, fonts, gpg and a dash directory, plus a docs directory and an editor configuration.

So the configuration covers several graphical applications that appear nowhere in the what is in there list. That is not a criticism of the list, which reads as a summary, but it does mean the repository description and the feature list are both narrower than the tree. The description names Ghostty and cmux, a terminal and a multiplexer, and neither appears in the feature list or in any directory name visible at the top level, which is the opposite discrepancy: applications configured somewhere below the surface.

The inspirations credited at the end explain the shape. Two well known dotfile repositories are named along with a set of writing about the subject, including a piece on improving command line habits, a retrospective on a decade of dotfiles, a post about setting up a new Mac quickly and a guide to installing and configuring zsh. The Mac-specific, Homebrew-installed, symlinked design follows from that lineage rather than from a general purpose manager.

## Conclusion

This is one person's working configuration rather than a dotfile manager, and it is best read as a description of a setup you would fork rather than install. Fork it, as the file asks, and delete what you do not use; the automated script exists to be edited. Two things to check before you run anything: whether the manual four-script path or the single script fits your tolerance for changes to your home directory, and whether the .local files are where you keep anything you would not want a git pull to touch. The macOS requirement is real, and the repository does not describe a path to Linux.

## FAQ

### What does nicksp/dotfiles require before installing?

macOS, Homebrew and Zsh, with the install script installing Homebrew and Zsh. You are also asked to switch your DNS to Cloudflare addresses, set up an SSH key for GitHub and test it with ssh -T git@github.com, configure GPG commit signing and install the MonoLisa font.

### How do I install nicksp/dotfiles manually?

Clone the repository to ~/dotfiles and run four scripts in order from its root: ./setup/zsh.sh, ./setup/brew.sh, ./setup/misc.sh and then ./setup/symlinks.sh.

### What does the setup.sh script in nicksp/dotfiles do?

It installs all the required dotfiles in your home directory as symlinks, after which everything is configured by modifying files in ~/dotfiles. The file marks it as use at your own risk.

### How do I keep machine specific settings out of nicksp/dotfiles?

With three local files that are picked up automatically if they exist: ~/.zsh.local sourced after the other shell files, ~/.ssh/config.local included after the public SSH hosts, and ~/.gitconfig.local included after ~/.gitconfig. Each can add to or override the managed configuration.

### How do I update nicksp/dotfiles?

By pulling in ~/dotfiles and running ./setup.sh again. The updating section uses the single script rather than repeating the four manual setup scripts, so manual installers converge on the automated path on their first update.

### What tools does the nicksp/dotfiles repository use?

pnpm 11.1.3 with Node 24 or later, Prettier 3.8.3 and prettier-plugin-sh 0.18.1 for formatting shell scripts alongside other file types, and a single dependency, avif, in the private package manifest. The check script runs bin/lib/check.

## Sources

- [Issues](https://github.com/nicksp/dotfiles/issues)
- [License: MIT](https://github.com/nicksp/dotfiles/blob/main/LICENSE)
- [nicksp/dotfiles on GitHub](https://github.com/nicksp/dotfiles)
- [Project website](https://github.com/nicksp/dotfiles)
- [README](https://github.com/nicksp/dotfiles/blob/main/README.md)

---

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