Sin-cy dotfiles and a macOS setup managed with GNU Stow

A dotfiles repository, and what the README admits about it

The repository description is the never ending updates of my dotfiles config, and the README opens by saying the directory contains the dotfiles for my mac system which probably won't work on yours.

That sentence is worth reading twice, because it is the honest framing of a category of project. A dotfiles repository is a personal environment expressed as files, and the value of someone else's is that the decisions are already made. The cost is that the decisions are made for their machine, their keybindings, their package managers, their fonts, their display, their private work habits. Nobody else has that context.

The primary language listed for the repository is Lua, which is a slightly odd signal and points at one part of the stack rather than the whole. The top-level directories show what is actually here: aerospace, alacritty, atuin, fastfetch, ghostty, herdr, karabiner, mactop, mpd, nvim, rmpc, sketchybar, starship, tmux, wezterm, workmux, zed and zsh, plus install.sh and a scripts directory.

Read that list as a picture of one person's macOS. There are three terminal emulators in it, alacritty, ghostty and wezterm, alongside tmux and a workmux tool that appears to manage terminal multiplexer sessions. There are two status line systems, starship for the shell prompt and sketchybar for a macOS menu bar. Karabiner is a macOS keyboard remapping utility, and aerospace is a window manager for macOS.

The audience is a macOS developer who recognises most of those names and wants the configuration rather than just the list.

The install script and the manual route

There are two installation paths, and the README is careful about the order.

The script route starts with optional prerequisites. Install the Xcode command line tools with xcode-select --install, then install Homebrew with the curl command, then install git, clone the repository into $HOME/dotfiles, make the install script executable with chmod +x ~/dotfiles/install.sh, and run it with /bin/bash ~/dotfiles/install.sh.

The manual route spells the same steps out in more detail, and it is the one worth reading, because it lists the tools that get configured.

The Homebrew extras are the substance of the setup: neovim, eza, fzf, fd, stow, bat, zoxide, zsh-autosuggestions, zsh-syntax-highlighting, git, starship, tmux and nvm. There is also coreutils installed separately, with a note to add PATH="/opt/homebrew/opt/coreutils/libexec/gnubin:$PATH" to the top of the rc file, and a note that if Mason lsp starts shouting when opening neovim you should run nvm install node v23.3.0.

Two optional pieces are cloned rather than installed from Homebrew. fzf-git comes from junegunn, and the tmux plugin manager tpm goes to ~/.tmux/plugins/tpm.

So the toolchain is: GNU Stow for the file management, tmux with tpm for sessions and plugins, Neovim with Mason for language servers, zsh with autosuggestions and syntax highlighting, Starship for the prompt, zoxide and fzf for navigation, bat and eza as replacements for cat and ls, and atuin for shell history.

Stow needs the home directory to exist first

The installation of this repository using stow has a precondition that catches people, and the README flags it in bold.

First you check out the repository in your $HOME directory with git clone, then cd dotfiles. Before running any stow commands, you have to make sure the home directory is set to have the same structure as the config structure, with the note to watch for sub-directories. If a subdirectory such as ~/.config does not exist in $HOME, you create it with mkdir .config, and other config files that do not exist in $HOME should not have any problems for the stow symlinks.

The reasoning is straightforward once you understand what stow does. Stow does not copy your configuration into place, it creates symlinks from your home directory into the package directories in the repository. If the target directory does not exist, the symlink has nowhere to point, and the result is either an error or a link into a path that does not exist. Creating the directory first is a one-line fix for that.

Once the structure is right, the README says that running stow . should be enough, with the important reminder to make sure you are in your dotfiles directory. For assurance it gives the per-directory form:

stow -t ~ starship wezterm tmux

#or run them separately

stow -t ~ nvim
stow -t ~ zsh

The -t ~ flag sets the target directory to your home, which is what makes the package names resolve to ~/.config and similar locations rather than relative to the current directory.

What the directory listing tells you about the setup

The top-level directory list is more informative than the README, because it is the actual configuration surface.

The shell side is zsh, and the prompt is starship. The editor is nvim, so Neovim, and the README's note about Mason lsp shouting when opening neovim suggests a Neovim setup with language servers configured through Mason. Alongside that, nvm is installed for Node version management, and the note about running nvm install node v23.3.0 is about making the LSP servers work rather than about the shell.

Terminal work is split across three emulators, alacritty, ghostty and wezterm, with tmux for multiplexing and a workmux directory that suggests session management on top of tmux. On the monitoring side there is fastfetch for system information, mactop for a macOS activity view, mpd and rmpc for music, atuin for shell history with search, and sketchybar for a menu bar display.

The macOS-specific pieces are the interesting part. Karabiner is the keyboard remapping layer, and aerospace is a tiling window manager for macOS, which tells you this is a macOS-native desktop setup rather than a terminal-only one with a Mac host.

For anyone reading this as a reference, the layout is a good map of what a Mac power user's configuration tends to contain, and the per-directory structure means you can adopt one piece, such as the zsh directory, without linking the rest.

Why dotfiles are worth adopting carefully

The honest case against running someone else's dotfiles wholesale is stronger than the case for, and the README's own first sentence concedes it.

The first problem is that a dotfiles repository encodes decisions you did not make and cannot see the reasoning for. A keybinding, a prompt format, a plugin set, a window manager tiling behaviour: each is a settled choice that now has to be undone if it does not suit you, and undoing it is more work than not installing it.

The second is the destructive direction. A configuration that replaces your shell rc, your Neovim config or your tmux config can break a working environment, and recovering means knowing what the file did before. The stow approach is gentler than a copy, because it symlinks rather than overwrites, and a symlink can be removed. That is a genuine reason to prefer a stow-based setup over one that writes files into your home directory.

The third is drift. The repository description calls itself the never ending updates of my dotfiles config, and the last push was on 2026-10-20, so this is a configuration that changes over time. A dotfiles repository that is a fixed snapshot can be trusted; one that moves under you means your own environment changes when you pull.

None of which makes it a bad project. It makes it a project to adopt selectively, and the directory-per-application layout plus the per-directory stow commands are what make selective adoption practical.

Licence, maintenance and what a dotfiles repository cannot carry

The licence is GPL-3.0, which is worth noting for a configuration repository. The practical effect for a personal dotfiles setup is minimal, since you are not distributing it, but if you forked this and published your own version, the copyleft terms of the configuration files would follow. No legal advice is offered here beyond naming the identifier.

The repository is not archived and the last push was on 2026-10-20, so it is being worked on continuously. There are no GitHub releases, which is normal for a dotfiles repository, where the main branch is the artefact.

What a dotfiles repository cannot carry is the part of a setup that is not a file. Your terminal font, your display arrangement, your system shortcuts, the hardware you are on, the private repository access you have, the accounts you are signed into. Those live outside the repository, and the README is candid that the configuration is for the author's mac system specifically.

The most useful way to read a repository like this is as a worked example rather than a package. Read the nvim directory to see how a Neovim configuration is organised, read the zsh directory to see how the shell is put together, and adopt the two or three pieces that you understand rather than the whole thing. The stow layout supports that approach, and the alternative, copying an entire home directory configuration from a stranger, is how people end up with a shell they cannot debug.

Editorial conclusion

Sin-cy dotfiles is a good fit for a macOS developer who wants a working Neovim, tmux and terminal setup to start from rather than assemble, because every tool is configured already and the stow structure makes it easy to take one piece without the rest. It is a poor fit if you want a portable configuration, since the readme says outright that it is for the author's mac system and probably won't work on yours, and a poor fit if you are not comfortable with stow symlinks and a cloned home directory. Before adopting, read install.sh rather than running it, check that the tool list matches the apps you actually use, and pick a specific stow target to link first, since running stow . in a directory whose subdirectories do not yet exist in your home directory will not link cleanly.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Sin-cy/dotfiles on GitHub