nicksp/dotfiles: A macOS Developer Environment Built Around Zsh and Homebrew
My personal dotfiles: Zsh, Git, VSCode, Obsidian, Ghostty, cmux, etc.
At a glance
- What is it?
- nicksp/dotfiles is a personal macOS configuration repository by Nick Plekhanov that provides a symlink-based dotfiles setup covering Zsh with Starship, Git aliases, fzf, VSCode settings synchronization, Obsidian configuration, Firefox custom styles, coding agent configs, and a custom Squirrelsong color scheme.
- Who is it for?
- nicksp/dotfiles is a well-structured starting point for a macOS developer who wants to see how one engineer organises Zsh configuration, Git aliases, Starship theming, and VSCode settings into a single maintainable repository. Fork it first rather than cloning directly: the README explicitly recommends forking to adapt it to your own needs, and the setup.sh script runs with a caution warning.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 114 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 1, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What This Repository Is and Who It Is For
nicksp/dotfiles is a personal configuration repository maintained by Nick Plekhanov for setting up a macOS development environment from a clean install. It covers shell configuration, Git, VSCode, Obsidian, Ghostty, Firefox, coding agent configuration, and a custom color scheme called Squirrelsong.
The repository is explicitly designed as a fork-first reference, not a one-click install for strangers. The README opens with a recommendation to fork before using, and the automatic installer carries a prominent caution warning. This framing is honest about the purpose: the value is in the patterns and organization, not in a portable setup that works identically on any machine.
The intended user is a macOS developer who wants to study how an experienced engineer structures dotfiles, borrows the configuration patterns they find useful, and builds their own version from the fork. The README includes links to the projects that inspired it: holman/dotfiles, mathiasbynens/dotfiles, sapegin/dotfiles, and several blog posts on CLI tooling and dotfiles management.
The repository requires macOS, Homebrew (installed by the setup script if missing), and Zsh (installed via Homebrew). There is no Linux or Windows support documented.
What the Repository Includes
The README lists the major components. The shell layer is built around Zsh with a custom Starship theme at tilde/.starship.toml, fzf integration at zsh/fzf.zsh, and Zsh aliases at zsh/aliases.zsh. Git configuration lives at tilde/.gitconfig with a set of Git aliases.
The agents/ directory provides coding agent configuration automation. The bin/ directory contains handy CLI scripts. The vscode/ directory handles VSCode settings synchronization. The obsidian/ directory configures Obsidian as a second brain knowledge management setup. Firefox custom styles are in firefox/.
The colors/ directory holds the Squirrelsong custom color scheme, which is available as an alternative app icon theme through the icons/ directory. The setup/macos.sh script applies sensible macOS defaults.
Extra tools include lazydocker/ and lazygit/ configurations, syntax highlighting configuration, a rectangle/ window manager configuration, and nimble-commander/ settings.
The package.json shows pnpm 11.1.3 as the package manager and Node.js 24 as the minimum version. The devDependencies include prettier and prettier-plugin-sh for formatting shell scripts and configuration files. The avif dependency is listed as a runtime dependency, suggesting image conversion tooling in the CLI scripts.
Installing the Dotfiles: Manual and Automatic Paths
The README documents two installation paths. The manual path gives more control and is appropriate for anyone who wants to inspect each step:
git clone [email protected]:nicksp/dotfiles.git ~/dotfiles
cd ~/dotfiles
./setup/zsh.sh
./setup/brew.sh
./setup/misc.sh
./setup/symlinks.shThe automatic path runs the full setup in one script:
git clone [email protected]:nicksp/dotfiles.git ~/dotfiles
~/dotfiles/setup.shThe README marks the automatic path with a caution: use at your own risk. This is standard advice for dotfiles installers because the symlinks.sh step replaces any existing configuration files in the home directory with symlinks pointing into ~/dotfiles. Running it on an existing setup without reviewing what it will replace can overwrite configurations that are not in the repository.
After installation, everything is configured by editing files in ~/dotfiles. Running `git pull` followed by `./setup.sh` updates the configuration. The README also documents utility commands: `set-defaults` applies the macOS defaults script, and `sync-color-themes` installs the color themes.
The pre-requisite steps the README lists before running either installer are: pointing DNS to Cloudflare at 1.1.1.1 and 1.0.0.1, configuring Git and GitHub SSH keys, setting up GPG commit signature verification, and installing the MonoLisa font.
Local Customization Without Modifying the Repository
A well-designed dotfiles repository separates the shared configuration from machine-specific settings. nicksp/dotfiles handles this through three override files that are automatically included if they exist but are not tracked in the repository.
~/.zsh.local is sourced after all other shell files. It is the place for additional aliases, environment variables, PATH additions, or anything that should not be shared in a public repository.
~/.ssh/config.local is included after the public SSH host configuration. Additional SSH hosts that are not public go here.
~/.gitconfig.local is included after the main Git configuration at ~/.gitconfig. The README specifically recommends using this file for sensitive information such as Git user credentials for individual repositories, since those should not be committed to a public dotfiles repository.
This three-file pattern is a standard approach in mature dotfiles repositories and is one of the design decisions worth studying from this repository.
How This Repository Compares to Dotfiles Frameworks
GNU Stow is a common alternative approach to dotfiles management. It acts as a symlink farm manager: you organize files in a directory structure that mirrors the home directory, and Stow creates the symlinks automatically. The advantage is that Stow handles the symlink creation declaratively without a custom script. The disadvantage is that it requires GNU Stow to be installed and requires the user to understand Stow's package structure.
nicksp/dotfiles uses a custom symlinks.sh script instead, which is the approach taken by many individual dotfiles repositories. This makes the repository self-contained but ties the installation process to the maintenance of that script. The README does not document every file that symlinks.sh will place, so users should read the script before running it on a machine with existing configuration.
Chezmoi, another dotfiles manager, adds templating and secrets management on top of symlinking. That is appropriate for configurations that need to vary across machines or include secret values. nicksp/dotfiles handles machine-specific variation through the .local override files rather than templates, which is simpler but requires more manual management when the same repository is used across multiple machines with different configurations.
Maintenance and Licensing
The repository is licensed under MIT, which permits use, modification, and redistribution. The last push was on 2026-06-09. There are no GitHub releases.
The README's homepage is listed as the repository itself (https://github.com/nicksp/dotfiles), which is typical for personal dotfiles repositories. The package.json shows version 0.0.1, consistent with a personal configuration repository that does not follow a conventional versioning scheme.
The CONTRIBUTING note in the README asks that pull requests only fix bugs or add improvements without any breaking changes, which is the appropriate policy for a personal dotfiles repository that others fork and adapt.
Editorial conclusion
nicksp/dotfiles is a well-structured starting point for a macOS developer who wants to see how one engineer organises Zsh configuration, Git aliases, Starship theming, and VSCode settings into a single maintainable repository. Fork it first rather than cloning directly: the README explicitly recommends forking to adapt it to your own needs, and the setup.sh script runs with a caution warning. The last push was on 2026-06-09.
Frequently asked questions
How do I install dotfiles from a GitHub repository?
Clone the repository to your home directory, then run the setup script. For nicksp/dotfiles specifically, clone to ~/dotfiles and run ./setup.sh for the automatic path, or run the individual scripts in setup/ one by one for the manual path. The setup script creates symlinks in the home directory pointing back into ~/dotfiles.
Should I clone or fork nicksp/dotfiles?
The README explicitly recommends forking the repository rather than cloning it directly. Forking lets you commit your own changes, local overrides, and machine-specific settings to your own copy without pulling in upstream changes that may conflict with your modifications.
How do I keep machine-specific settings out of the shared dotfiles repository?
nicksp/dotfiles uses three override files that are sourced automatically but not tracked in the repository: ~/.zsh.local for shell configuration, ~/.ssh/config.local for SSH hosts, and ~/.gitconfig.local for Git credentials and per-repository settings. These files are created on the local machine and never committed.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/nicksp-dotfiles)